Virtual ][ Help

#
Virtual ][

Copyright © 2003-2013, Gerard Putter

### Overview

> Introduction
> About the ROM image file
> Run a demo to test the installation
> Where to find Apple II documentation
> About the evaluation version and licensed versions
> Starting and stopping the program
> General operation

### Devices

> The Apple ][ keyboard
> Working with disk images
> 5.25" floppy disk drive
> Hard disk and 3.5" floppy disk drive
> Printer
> Serial interface
> Cassette recorder
> 80-column card for the Apple ][ and Apple ][+
> 80-column display on the Apple //e
> AppleMouse
> Real time clock
> Z80 card and CP/M

### Gameplay and other fun stuff

> Joystick and game paddles
> Working with sound
> Using different screen sizes and fullscreen
> Recording a movie

### Transferring Apple II diskettes to the Mac

> The A2V2 utility program

### Advanced options

> Working with character sets and international keyboards
> Configuration
> Controlling Virtual ][ with AppleScript
> The Virtual ][ Inspector

### Support

> Getting support
> Release notes

### Other issues

> Specifications of the virtual machine
> Unsupported features
> Why did I create this application?
> Acknowledgements

### Introduction

Virtual ][ is a program that emulates the Apple ][ computer. Its main purpose is to enjoy, on your Macintosh computer, the nostalgic fun of the Apple ][.

Key features

- Emulates the Apple ][, ][+ and //e
- Supports USB game pad or joystick
- Save a running machine and resume later on
- Full-screen mode
- Epson FX-80 and ImageWriter II printer emulation
- Conversion of original diskettes to disk image files
- Integrated "Spotlight" module allows searching for a specific file on your disk images.

More features

- Run multiple machines simultaneously
- Supports all graphics and text modes
- Emulates the internal speaker
- Mouse ][ emulation
- ProDOS hard disk support
- Thunderclock, "Mountain" AppleClock and no-slot clock
- Cassette tape emulation
- Memory expansion up to 8MB
- Supports "international" keyboards and character sets
- Record a QuickTime movie from the emulated Apple II screen
- Intuitive user interface
- Realistic sound effects
- Comprehensive documentation

Advanced features

- Configure your own virtual machines
- Mount a Mac folder as a DOS or ProDOS disk
- Run CP/M on the emulated Z80
- Use real serial devices with the emulated Super Serial card
- Paste text to the Apple ][ keyboard
- Install your own character generator ROMs
- Supports "variable speed" mode for better performance
- Debug Apple II programs with the "Inspector"
- Built-in performance monitor
- Can be controlled with AppleScript

Virtual ][ accurately implements the hardware of the original machine in software, so all programs should behave like they did on the real machine.

The program requires Mac OS X 10.6 "Snow Leopard" or better. There are no specific hardware requirements.

Note that, for reasons of copyright, the application does not come with the original Apple ROM images. For more information on this, read "About the ROM image file".

You can download and try an evaluation version of Virtual ][ for free. If you like the program, you can buy a license and enjoy the full-featured Apple ][ emulation. Read more about this in "About the evaluation version and licensed version".

### About the ROM image file

#### Installing a ROM image file

The first time you start Virtual ][, you'll probably see a notice about a missing ROM image file. Virtual ][ can emulate three different machines: the Apple ][, the Apple ][+ and the Apple //e. Each machine needs a different ROM. This is how to install one or more ROM files.

- First of all: the Apple II ROM contains software, and in order to legally use it, you must be licensed to do so. This goes for all software, including the Apple II ROMs. If you own an original Apple II you are implictly licensed to use the ROM software contained in that machine. The ROM is not part of the Virtual ][ license!
- You do not have to make a copy of the ROM in your original machine, because ROM image files can be found on the Internet. For example in the Asimov FTP archives. You can also search via Google. The files you need typically have names such as apple_iie_rom, apple_ii+_rom or apple2o. If you're not sure which ROM files you need, just install a few and see what happens. The names of the ROM files must end in .rom (or .ROM). Apart from that, the names are ignored by Virtual ][ - it will automatically recognize the files it needs, and ignore the rest.
- Once you have obtained one or more ROM image files, put them in the folder where the Virtual ][ application is located.
- From the File menu, use "New Machine" to create an instance of the machine you want to emulate, as shown in the next picture. The program will automatically search the application folder for a ROM file that matches the selected machine type. If no such file can be found, the program shows a warning.

#### Some technical background

In each Apple ][, the memory address range from $D000 to $FFFF is occupied by ROM, containing the Basic interpreter (either Integer Basic or Applesoft Basic) and the system monitor. In the Apple //e, part of the memory range $C100 - $CFFF is also used for ROM.
Virtual ][ needs a valid ROM image file to behave like a real Apple II. Because the ROM's are copyrighted by Apple, they are not bundled with Virtual ][. The ROM's must be present as external files containing the exact memory image. To be more precise: Virtual ][ uses the last 12 KB of the designated file (16 KB in the case of Apple //e) as the ROM of a newly created virtual machine.
If the program does not find the ROM file, it uses a built-in ROM image, which is only able to issue the notice on the missing ROM image file.

If you want to use a non-standard ROM, and know what you are doing, you can override the standard ROM image file search, and specify a ROM image file in the "ROM memory" section of the configuration window.

###

Run a demo to test the installation

After you have installed the ROM image files, you can immediately test whether the installation was successful, and see some of the program's highlights at the same time.

To that purpose, click on the Applescript menu, and select any of the "example scripts".

You'll see a short explanation of what the demo will do; when you click the "Run" button the demo will start.

If you want to learn more about using Applescript with Virtual ][, you should read Controlling Virtual ][ with AppleScript

###

Where to find Apple II documentation

This Help file explains everything about using the Virtual ][ program. It tells you for example how to configure a virtual machine, how to use the emulated printer and how to work with disk images.
It does, however, not explain how to use the Apple II computer. If you want to refresh your memory on Applesoft Basic, Integer Basic, DOS or ProDOS commands, you might find this web page useful: Apple ][ Programmer's reference. Or, if you want more detailed information, have a look at this site; it contains a large collection of Apple II manuals.

### About the evaluation version and licensed versions

The program runs in one of three license modes:

- Evaluation mode; this is what you get when you first download the program and run it. Most of the program functions work, but the program pauses every few minutes.
- Limited license mode: this lifts some of the restrictions of the evaluation mode. This license is mainly intended for users who want to play the old Apple ][ games.
- Full license mode: this lifts all restrictions and unlocks the full power of the program.

This table shows the difference between the licenses:

| Evaluation | Limited ($19) | Full ($49)
"Evaluation Version" watermark in screen | Yes | No | No
Pauses every five minutes | Yes | No | No
Full use of matrix printer emulation (without "Evaluation Version" watermark) | No | No | Yes
Record a movie of the emulated screen | No | No | Yes
Can mount a Mac folder as a ProDOS disk | No | No | Yes
Maximum amount of emulated memory | 128 KB | 128 KB | 8 MB
You're entitled to all future improvements of the program | No | No | Yes
Intelligent power management (as described in Setting the speed) | No | No | Yes
Can resume a machine from a previous session | No | Yes | Yes

A license gives you the right to run Virtual ][ on one computer at a time (you can install it on multiple computers though).
Buying a license is easy. Just click on the button below, or choose "Buy a License" from the application menu in Virtual ][. Either option will take you to the website of the Kagi store. There you can choose to buy the limited license, the full license or an upgrade from limited to full.
As soon as you have paid for the license, Kagi sends you an e-mail containing a license code. Choose "Enter License Code" in the Virtual ][ application menu, and enter the information received in the e-mail.
When everything checks out, the program is upgraded to the licensed version immediately. There is no need to stop and restart the program.

###

Starting and stopping the program

#### Starting

There are two ways to start the Virtual ][ application:

1. Double-click the application and work with a default configuration, or
2. Open a Virtual ][ document and work with a machine you configured yourself.

In either case, the program requires a ROM image file to boot a virtual machine. This is described in more detail in "About the ROM image file". Assuming a valid Apple //e ROM image is available and the program is started by double-clicking the application icon, it creates a default virtual machine and shows the main window.

#### Stopping

A virtual machine stops (is "switched off") when you close its window (or when you stop the Virtual ][ program). When you do, the program presents a sheet asking if it should save the virtual machine.

The entire state is saved in a document, and when you later on open such a document, the virtual machine continues running from where it left off. This can, for example, be used to interrupt a lengthy game and continue playing at a later time.
Note however that saving the complete machine state has a few limitations:

- Unsaved print output produced by the matrix printer emulation is not retained. See "Using the printer" to learn how to save the print output.
- The state of mounted Macintosh folders is not saved.
- It is not recommended to save the state while output is being written to a disk or tape. The data might be corrupt when the state is restored later on.

Instead of saving the complete machine state, you can also choose to just save the machine configuration. When you open a file saved this way, a machine is constructed with the configured components, and the machine is "switched on". In this case it does not continue a previous run, but starts from scratch.

#### Changing starting and stopping behavior

The "default machine" defines the type of virtual machine the program creates when it is started. You can easily configure the program to use a default configuration of your choice. To save the current machine as the default, select the option "Make This the Default Configuration" in the Machine menu. Alternatively, select "Preferences" from the Virtual ][ menu. The preferences window allows you to select a pre-configured machine as the default.

If you never want to save the state of a running virtual machine, you can tell the program to skip the "save state" sheet when a virtual machine is closed. When this option is selected, you can always change your mind and still save the machine state by holding down the "ctrl" key while closing the window.

###

General operation

This is what the main window looks like when the program is started, assuming the correct ROM image has been installed. On your Mac the window might look slightly different, because Virtual ][ initially determines a window size that best matches your screen.

The main part of the window is the Apple ][ screen. In the example it emulates a monochrome green monitor, but the leftmost two buttons in the toolbar make it easy to show a color monitor, or to change "green" to a different color (like amber).
The screen as shown in the example is what an Apple //e shows when it is turned on: it waits for a bootable diskette. You can get the Applesoft prompt by pressing Reset (emulated by control-F12 or the Reset button in the toolbar).
The bottom part of the window is a "drawer" that shows the connected devices. The devices in the default configuration are:

- Two disk drives, connected to a card in slot 6;
- A matrix printer, connected to a card in slot 1;
- A cassette tape recorder.

Furthermore, the drawer contains four small icons at the left; this is the "media" section, representing diskettes and cassette tapes. Each icon in the devices drawer actually is a button. The way these buttons and the devices work is described in the next chapters.

#### Default configuration

This is what the default configuration looks like. The default machine is an Apple //e with

- A 64K RamWorks card in slot 0 (making a total of 128 KB memory);
- A Grappler+ card in slot 1;
- A Z80 card in slot 2;
- A Mockingboard card in slot 4;
- An Apple mouse card in slot 5;
- A Disk ][ card in slot 6;
- A Thunderclock Plus card in slot 7.

You can change the configuration to your liking, as explained in the "Configuration" section.

#### Copying the screen to the Macintosh clipboard

The contents of the Apple ][ screen can be copied to the Macintosh clipboard. This can be done in two ways:

- The regular "Copy" command puts the screen contents on the clipboard as a picture.
- The "Copy as Text" command, also in the Edit menu, puts the screen contents on the clipboard as text. This usually results in exactly 24 lines of text. However, if the screen is in mixed text / graphics mode, only the 4 text lines are copied. The command is unavailable if the screen is in full graphics mode.

#### Temporarily pausing a virtual machine

A virtual machine can temporarily be paused by selecting "Freeze Virtual Machine" from the "Machine" menu, or by clicking the "Freeze" button in the toolbar. You can later on resume with "Resume Virtual Machine" or the same toolbar button. As a shortcut you can also use the F1 key to pause / resume.

#### Setting the speed

Virtual ][ faithfully emulates the speed of the original Apple machines, which was 1 MHz. Maintaining this exact speed is essential for programs that display animated graphics or produce sound. There are however situations where it would be nice to have a greater processing speed: while doing a lengthy calculation for example, or when accessing the floppy disk. To this purpose Virtual ][ has three modes of operation, which you can choose from the Machine menu or using the little "Speed" wheel in the toolbar.

1. Regular Speed: in this mode, the virtual machine runs exactly at the speed of the original machine. Use this for the genuine Apple ][ (or //e) experience.
2. High Speed: if this is selected, the machine runs as fast as it can, but falls back to regular speed when it writes output to the screen or produces sound. This mode is suitable for game play: some things go fast, like loading and initializing the game, but the game play itself runs at regular speed.
3. Maximum Speed: the machine runs as fast as it can, and only switches back to regular speed when it must produce sound. This option is intended for unattended tasks like printing, disk copying, compilations and so on.

If you have the full license version of Virtual ][, the high speed and maximum speed settings come with a power management feature: while the Apple II is "idle", in other words if it isn't doing anything useful, the speed is automatically reduced to "regular". This saves energy and enhances the battery life on a notebook Mac.
If you want, you can switch the power management feature off with the menu item "Regular Speed if Apple II is Idle", in the Machine menu.

Note that the highest effective speed that can be obtained depends on your Macintosh, on the number of simultaneously open virtual machines, and on other programs running at the same time.

You can preserve battery power even further by selecting the option "Pause virtual machines if minimized or hidden" in the "Power" section of the application preferences. The option is switched on by default.

###

The Apple ][ keyboard

#### Key mapping

The built-in keyboard of the Apple ][ computer has far fewer keys than your Macintosh keyboard. It even has hardly enough keys to produce the entire supported character set. For example, on the original machine the user had to press shift-M to produce the character "]", and shift-N for "^". The characters "[" and "\" could not be entered at all, although they were part of the character set.

These restrictions do not apply to the Virtual ][ emulator. All characters in the Apple ][ character set can be entered by typing the appropriate character on the Macintosh keyboard. This implies that shift-M just produces a capital M, not a "]".

#### The "soft caps lock" feature

The keyboard of the original Apple ][ and ][+ could not be used to enter lowercase characters. Typing any of the letters "a" to "z" produced uppercase "A" to "Z".
The Apple //e keyboard was able to enter uppercase and lowercase characters, but many programs still expected uppercase input only.
To emulate flexible keyboard behavior, Virtual ][ has the "soft caps lock" option. When it is on, the keys "a" to "z" produce uppercase letters, as on the original Apple ][ keyboard. When the option is off, these keys produce lowercase letters (or uppercase when shift is also held down), as on the Apple //e. This option can be toggled with the "Caps" toolbar button.

#### Special keys

The Apple ][ had four special keys that did not produce a character. Here is how they are emulated.

- Left and right arrow: these keys are emulated by the left and right arrow keys on the Macintosh keyboard. The Apple ][ keyboard did not have a "backspace" key, so the left arrow key is the official way to move the cursor to the left. In Virtual ][ you can also use the Macintosh backspace key, but you have to activate this feature in the keyboard configuration.
- Repeat key: The Apple ][ keyboard had no auto-repeat feature, but it provided a specific key for this purpose. This key is not implemented in Virtual ][. Instead, it uses the auto-repeat feature of the Macintosh keyboard.
- Reset key: This is an important key. It resets the 6502 processor and connected devices. On the Apple ][+, it had to be pressed together with the control key, in order to prevent an accidental reset. In Virtual ][, function key F12 acts as the Reset key, and just like on the Apple ][+, must be pressed together with the control key. Another way to emulate the Reset key is to choose "Reset" from the Machine pull-down menu or click the Reset button in the tool bar.
  For reasons of compatibility with previous versions of Virtual ][, ctrl-Backspace also acts as Reset, but this only works for the Apple ][ and Apple ][+, not for the Apple //e.

#### Additional keys on the Apple //e

- The up and down arrow keys are emulated by the same keys on the Macintosh keyboard.
- The Solid Apple key is mapped to the Macintosh "alt" key. Note that there can be a conflict here when you need the alt key to enter a specific character on the Macintosh keyboard. In that case, no "solid Apple" will be sent to the virtual machine. For example, on a Macintosh with a French keyboard you must type alt+` to get the character @ (this goes for any program, not just Virtual ][). So on such a keyboard it is not possible to enter solid Apple+@ in the virtual machine. On US and European ISO keyboards this is not an issue, because the alt key is never needed to type any of the standard ASCII characters.
- The Open Apple key is mapped to the Macintosh "Command" key, but there are some restrictions here, because Command is also used for Macintosh menu shortcuts. In full-screen mode, the Command key works just as Open Apple, so for example you can type Command-c to have the Apple //e program running in the virtual machine perform a Copy command. The only exception is Command-Enter, which ends full screen mode.
  In windowed (non full-screen) mode, you must press the Command key twice in succession (like "double click"). So in this case Command-Command-c would send the Copy shortcut to the virtual Apple //e, whereas just Command-c causes Virtual ][ to copy the Apple //e screen to the Macintosh clipboard.
- The "Delete" key (located at the upper right of the Apple //e keyboard) is emulated by the Macintosh backspace key, unless the option "Backspace is left arrow" has been set in the keyboard configuration. In the latter case the Delete key is not available.

#### Pasting the Macintosh clipboard

If the Macintosh clipboard contains text, it can be pasted into the virtual machine. The behavior is as if each individual character were typed on the keyboard. This "typing" occurs as fast as the Apple ][ can accept the characters, so no characters are lost in the process. If the Apple ][ is not reading the keyboard when the text is pasted, the text remains queued. Manual input is disabled as long as a pasted text is being entered into the Apple ][. A "newline" character in the text is converted to the "Return" key on the Apple ][.

###

Working with disk images

#### Overview

A disk image is a representation, in a single Macintosh file, of an entire floppy disk or hard disk. Apple II disk image files come in several different formats; the next table shows the formats supported by Virtual ][.

Disk image type | File extension | Description
5.25" diskette | .dsk, .do, .po | A regular diskette with 35 to 40 tracks, used with DOS, ProDOS, UCSD Pascal or CP/M. The size of the disk image file is 140 KB for a 35 track disk, up to 160 KB for a 40 track disk.

Copy protected 5.25" diskette

.nib

A disk in so-called "nibbilized" form. This is a low-level representation, which allows for disks that were originally copy-protected. The format can also be used to represent 13-sector disks (DOS 3.2). The size of a nib image is 232960 bytes for a 35 track disk, up to 266240 bytes for a 40 track disk.
This format supports most, but not all, features of the Disk ][ drive.

Copy protected 5.25" diskette (proprietary) | .v2d | A proprietary format, capable of supporting all features of the Disk ][, including "half-tracks" and tracks of non-standard length. The format is compatible with the "D5NI" format used by one of the first Apple II emulators, "Stop The Madness". You won't find disks with this format on the Internet, but Virtual ][ might create such a disk image when the other formats fall short.
Compressed 5.25" diskette | .gz, .gzip | Any of the above diskette types, compressed with the gzip utility. Many Internet archives offer diskettes in this form, to save space and bandwidth. Such files can directly be used in Virtuall ][, without the need to expand them first.
Hard disk or 3.5" diskette | .2mg, .2img | A widely used, universal disk image format.

Hard disk or 3.5" diskette (legacy format)

.hdv

A disk format based on one of the Mac Classic DiskCopy formats, "NDIF R/W". If you have DiskCopy disk images, there is a good chance you can convert them to the .hdv format by selecting "Convert Legacy Disk Images" from the Media menu. This starts a utility program that allows you to select one or more disk image files and then tries to convert them. When successful, the converted disk images are saved with the ".hdv" extension in the same folder as the original. The original disk images remain untouched. Note the conversion works one-way only.
For the technically interested: the hdv format is extremely straightforward: it just contains all 512 byte disk blocks in ascending order.

Apart from disk images, Virtual ][ also lets you mount a Macintosh folder as an Apple ][ floppy disk or a ProDOS hard disk; this provides a way to copy files from one environment to the other.
Another way to copy files from the Macintosh to the emulated Apple ][ environment and vice versa is the application "ADFS" by David Cotter.

#### Converting original Apple ][ diskettes to disk image files

How do you obtain disk image files? First of all, you can find them on the Internet, for example in the Asimov archives.

However, Virtual ][ can also help you converting original Apple II diskettes to disk images, with the A2V2 utility program. If you still have an original Apple ][ with a working disk drive, Virtual ][ can help you converting original diskettes to disk image files. To this purpose, select "Convert Apple II Diskettes" from the "Media" menu. This will start a separate program, named A2V2 (short for Apple ][ - Virtual ][). Read the program's Help section to learn how to do the conversion. A2V2 can convert in both directions: from diskettes to disk image files and vice versa.

Because the capacity of an Apple ][ diskette is very small by todays standards (typically 140 KB), you might end up with many diskette image files. Virtual ][ offers several ways to keep track of the diskettes and their contents.

These options are discussed below.

#### Organizing your disk image files: create a "favorite disk folder"

If you don't have too many disk images, it is recommended to put all your disk images in one folder (with subfolders as necessary), and to make this the "favorite disk folder" in the Virtual ][ preferences. That way you can use the "Disks" button in the toolbar to open your disks folder in the Finder. Combined with Apple's Exposé this is a convenient way to locate disk images and drag them to an empty Virtual ][ disk drive.

#### Organizing your disk image files: the "search" window

A powerful mechanism offered by Virtual ][ is a built-in search window. It lets you find the disk images that contain an Apple II file with a specific name, no matter where these disk images are on your Mac. This works for diskette images with extension .dsk, .po or .do, and their gzipped equivalents. It also works for hard disk and 3.5" disk image files. This feature relies on Apple's Spotlight technology, so the disk image files must be in folders that are included in the Spotlight search (by default your entire home folder, and everything in it, is included).

To use the feature, select "Search All Disk Images" from the "Media" menu.

When no disk image files appear at all, or when you feel there should be more disk images than are actualy shown, choose "Import Disk Images in Spotlight" from the Application menu. The search window will be updated while new disk images are found.

Initially, the window shows you all disk images belonging to the selected file systems (DOS, ProDOS, etc.). You can narrow down the displayed collection by typing (part of) an Apple II file name in the search field and pressing return.

For example, suppose you know you have the game "Raster Blaster" somewhere. but have no idea where exactly. Open the search menu, type the name you are looking for, and press return. This is what might appear.

Apparently, these disk images all contain a file with the requested name. To insert one of the disks in an emulated floppy disk drive, double-click its line, or drag it to a disk drive.

Because the search mechanism uses the Spotlight feature, you can also search disk images without starting Virtual ][, by just typing a file name in the system-wide Spotlight search field. Selecting one of the disk images from the Spotlight menu launches Virtual ][ with the selected disk inserted.

Note that when you select a disk image file in the Finder, and open the "Info" window, it shows you the Apple II file system.

Note further that so called "copy protected" disk images cannot be searched, because they usually have a non-standard file system. Such disks can however be used in Virtual ]['s emulated disk drives.

#### Quickly inspecting your disk image files using "QuickLook"

Virtual ][ contains a module for the Mac OS X QuickLook feature. It is installed automatically with Virtual ][, and allows you to quickly inspect the contents of most Apple II diskette and hard disk images. In the Finder, select the Cover Flow view, as shown in the screen snapshot. Alternatively, select a disk image and press the space bar to go to the QuickLook view.

#### Write-protecting a disk

An original Apple II diskette could be write-protected by closing its "write-protect notch" with a piece of tape. In Virtual ][ this can be done by selecting "Set Disk Properties..." from the Media menu. This not only works for diskettes, but also for hard disk images. As with the original Apple II, you can change the write-protect state only while the disk is not inserted in the drive.
Alternatively, you can select the disk image file in the Finder and set its "Locked" property in the Info window.

#### Setting volume numbers of DOS and ProDOS diskette images

In Apple II DOS and ProDOS, diskettes have a volume number, which is assigned when formatting the diskette. In Virtual ][, the equivalent of these diskettes are the disk images with file extension .dsk, .do and .po. These disk images only contain the diskette data, and not the meta data such as the volume number. For that reason they are assigned the default volume number 254 when you insert them in a disk drive.
This default volume number works fine in most of the cases, but sometimes Apple II software requires a specific volume number in order to run. To make this posible, Virtual ][ allows you to set a specific volume number, by selecting "Set Disk Properties..." from the Media menu. You can only change the volume number for diskettes while they are not inserted in the disk drive.
Thechnically, the volume number is stored as a so called "extended attribute" in the Mac file system.

###

Using the floppy disk drives

#### Supported disk image formats

The original Apple Disk ][ accepts 5.25" diskettes with 35 tracks. However, it was possible to move the disk drive arm to track 36, and some copy protection schemes actually relied on this. Furthermore, disk drives existed (not made by Apple) that supported 40 tracks. In order to support a wide range of disk formats, the disk drive emulation of Virtual ][ supports up to 40 tracks.
The 5.25" diskette image formats supported in Virtual ][ are listed here.

Apart form disk images, the disk drive accepts a Macintosh folder to be mounted as a DOS 3.3 diskette. This feature is described in more detail below.

#### Inserting and removing a disk

In order for a disk image to be inserted in a disk drive it must have the appropriate file extension: ".dsk", ".do", ".po", ".nib", ".v2d", "gz" or "gzip". Inserting a disk can be done in several ways: one is to click the appropriate media button in the device drawer and then select the disk image and the target drive in the file open panel that appears. The same can be done by selecting "Insert Diskette Image" from the "Media" menu.
In the file open panel you will also see a checkbox to make the disk image a part of the configuration. This means that when you save the configuration and later re-open it, the selected disk image is already inserted in the disk drive. This allows you to make a "turnkey" system, which automatically boots from an already inserted disk.

A different way to insert a disk is to simply drag the disk image file or shared folder from its Finder window (or from the disk search window) to an empty disk drive. An empty disk drive can be recognized by the opened drive door. Using this technique, you can still make the disk part of the configuration by holding down the "alt" key while dropping the file or folder.

The third way to insert a diskette is to double-click its icon in the Finder or in the disk search window. Note that double-clicking a gzip file in the Finder is an exception: it will result in the file being expanded by the gzip utility!
When double-clik a disk image, Virtual ][ will be started when it isn't running already, and the diskette is inserted in the disk drive with the highest slot number and the lowest drive number. This is the disk drive used for booting the machine, so effectively you can boot a DOS session by simply double-clicking the DOS boot diskette.
If Virtual ][ already runs when you double-click the diskette image, it will be inserted in any free disk drive. When no such drive is available, a new virtual machine will be created.

A disk can be removed by clicking on the disk drive. Note that a disk can be removed while it is being used for I/O; this is of course not recommended, just as with a real Apple ][!
If the disk image or mounted folder is part of the configuration, the program presents a confirmation dialog. Ejecting the disk removes it from the configuration.

#### Creating a new disk image

A new, uninitialized disk can be inserted by clicking the "new disk" media button.

In the dialog that appears, specify the name of the disk and the target drive. Just as with the real Apple ][, the new disk must be initialized by the operating system before it can be used. The disk is saved as a ".dsk" disk image.

#### Mounting a Macintosh folder

A Macintosh folder can be mounted as a DOS 3.3 diskette. This is an easy way to share files between a virtual machine and the Macintosh environment. What actually happens is that the files in the folder are converted to Apple DOS format (if necessary) and stored on a temporary (in-memory) disk image, which is inserted in a disk drive. When files are modified in the virtual machine, they are copied back (with conversion as necessary) to the Macintosh folder.
This approach implies that the Macintosh folder to be mounted is limited to the maximum diskette size DOS 3.3 can handle, which is approximately 200 KB. Furthermore, it must contain only files, not subfolders. The file names must adhere to the DOS 3.3 file name rules: the first character must be alphabetic, the file name must contain at most 30 characters and must not contain a comma. Virtual ][ checks on these conditions and will refuse to mount the folder if the conditions are not met.

In Apple DOS every file has a file type, such as A(pplesoft Basic), I(nteger Basic) or B(inary). In order to handle the files correctly, Virtual ][ must be aware of the DOS file type of every shared file. Furthermore, some files need conversion. A text file for example has different representations in Apple DOS and in OS X, so if you want to edit a DOS text file in the OS X environment it must be converted. Virtual ][ has a feature that allows you to specify the file type of each shared file, and the conversion rules if appropriate. A dialog window is automatically presented when a Macintosh folder is mounted that contains files with unknown DOS file type. You can also see the dialog when you choose "Assign Apple DOS Types" from the "Media" menu. This is what the dialog looks like:

The list presents all files and folders in the selected folder. Invalid files are marked with a little red cross, as are folders. Valid files that have already been assigned a DOS type have a green dot. Files that have never been assigned a DOS type appear with the exclamation mark icon, and are assigned type Binary by default.
You can use the popup menus in "Type" and "Macintosh Format" to change the settings. The next table lists your options:

DOS Type | Macintosh Format | Address
B (Binary) | No Conversion: the file is stored in the Macintosh folder exactly as it is stored on the DOS diskette. | Not Applicable
B (Binary) | Strip Prefix: in Apple DOS, all binary files have a 4 byte prefix, containing the load address and the length of the file. With this option, the prefix is omitted from the stored Macintosh file. | This specifies the load address to be used when converting the file to DOS format. You can enter a decimal number or a hexadecimal number preceded by '$'. So for example $2000 is the same as 8192.
T (Text) | No Conversion: the file is stored in the Macintosh folder exactly as it is stored on the DOS diskette. | Not Applicable
T (Text) | Macintosh Text: in Apple DOS, text files are encoded differently than on Macintosh. Select this option if you want to be able to edit the text file in the OS X environment. | Not Applicable

A (Applesoft Basic)
I (Integer Basic)
R (Relocatable)
S (Undefined)
X (Undefined)
Y (Undefined)

Always copied without conversion.

Not Applicable

Virtual ][ remembers the file types and conversion rules you assign, and it automatically uses these settings the next time the folder is mounted.

Note there are some special considerations when using shared folders:

- While a folder is mounted, you should not use another Mac OS X program to make changes to the corresponding Macintosh files. If you do, all changes will be lost as soon as the diskette is copied back to the Macintosh folder.
- It is possible, though not recommended, to re-format a mounted folder diskette with the INIT command. However, this reduces the capacity of the diskette to 140 KB.
- If a DOS file name contains the "/" character, the name cannot be used on OS X. In that case Virtual ][ converts the file name by changing all "/" to "\", and putting another "\" in front of the file name.
- Virtual ][ supports so called "sparse text files". This feature is used in Apple DOS to store random access files in a space-efficient way. A side effect is that such a file can appear to be be much larger in the Macintosh folder than it is on the DOS diskette.

###

Hard disk and 3.5" floppy disk drive

#### General description

Hard disks and 3.5" floppy disks share the same technical characteristics, and Virtual ][ supports both with an imaginary type of emulated disk drive, called "OmniDisk". This device can handle disk images of any size up to 32 MB (the maximum supported by ProDOS), including 400 KB and 800 KB floppy disk images.

The hard disk / 3.5" disk image formats supported by Virtual ][ are listed here.

Apart form disk images, the OmniDisk accepts a Macintosh folder to be mounted as a ProDOS hard disk. This allows for an easy way to exchange files between the Apple ][ and the Macintosh environments. Note this feature requires a full license to be fully functional.

#### Setting up hard disk drives

An OmniDisk must be connected to an emulated SCSI card, which fits in any free slot except slot 0. One SCSI card can control up to two OmniDisk drives. Refer to the chapter "configuration" for a description of how to insert an emulated card and connect devices to it.

#### Using the hard disk and 3.5" floppy images

Disk images can be inserted and ejected just like floppy disk images.
The main difference is you use the OmniDisk buttons in the devices view.

#### Using a Macintosh folder as a ProDOS hard disk

A Macintosh folder can be used as a ProDOS disk by "inserting" it in an OmniDisk drive. You can do this in two ways: either choose "Mount Folder as ProDOS Disk" from the "Media" menu, or simply drag a folder from the Finder to an empty OmniDisk in Virtual ][. Note that completing the operation might take a few seconds; the program has to plough through all files and sub-folders to determine the exact structure of the newly mounted disk.

A few restrictions apply to the mounted folder:

- The total folder size must not exceed 32 MB;
- Individual files are limited to 16 MB.

These restrictions are imposed by the ProDOS system. When Virtual ][ finds these conditions are not met, it will refuse to mount the folder.

While the folder is mounted, it is not accessible from the Finder. You'll notice the icon gets a lock and a "no entry" sign to indicate this.

Note that the mounted folder only works under ProDOS.

Every file and every folder in the mounted folder will be present on the ProDOS disk; any changes made on the ProDOS disk (like making new files and directories or changing existing files) result in the same change in the Macintosh folder. Note that a Macintosh file might have a name that is not allowed in ProDOS; in that case Virtual ][ composes an alternative name for use in ProDOS, but this name will be as close to the original as possible. The Macintosh file extension is used to determine the ProDOS file type. For example, ".BAS" is an Applesoft basic program, and ".TXT" is a text file.

The contents of text files are treated in a special way: the Apple ][ software expects each line to end with a carriage return character (ASCII 13), while Mac OS X expects a linefeed character (ASCII 10) to end a line. Virtual ][ automatically converts these codes while reading and writing text files. All other file types are stored in the Macintosh folder without any conversion.

When you use ProDOS to delete files or directories, the same items are deleted from the Macintosh folder. However, as you would expect on the Mac, they are not deleted right away but moved to the trash.

The mounted ProDOS folder disk is almost 100% compatible with a "real" ProDOS disk. You can even format it and install the ProDOS system on it, which will give you a bootable disk. The only thing not supported is making a full disk copy (block-by-block) to a mounted ProDOS folder disk. An attempt to do so will result in an error message.

You can store the state of a virtual machine while a folder is mounted as a ProDOS disk; in that case the folder will keep its access restrictions, because making any changes to the folder would render the saved state invalid and useless. When you open the saved state later on, the folder is mounted automatically and you can continue where you left off.

The restricted access to a mounted folder is lifted when you eject the disk by clicking the OmniDisk icon. From that point you'll have full access to the folder again in the Macintosh environment.
So what if Virtual ][ crashes while a folder is mounted? In that case the disk wasn't ejected, so the folder is inaccessible, and you won't be able to mount it again. To solve this, Virtual ][ has an option to reset the state of a mounted folder; you'll find it in the "Media" menu as "Reset Mounted ProDOS Folder". Use it in case of emergency only!

Finally, the mounted ProDOS folder is only fully functional when you purchased a full license for Virtual ][. If you don't have such a license, you can still mount a folder, and examine the directories in ProDOS, but you cannot read or write any files.

###

Using the printer

#### General description

Virtual ][ supports four different emulated printers:

- An Epson FX-80;
- An Apple ImageWriter II;
- A simple "text only" printer;
- Printing to the Macintosh clipboard.

The printer is represented by a "Printer" button in the devices drawer. While the Apple ][ is printing, the green light on the printer blinks. When you press the button, the printer goes offline and the program shows a print preview. You can also click the button with the "alt" key held down: this just sets the printer offline without showing the preview. Pressing the button a second time sets the printer online again.

#### The Epson FX-80 printer

The Epson FX-80 was a very popular printer in the 1980's, and is therefore supported by many Apple ][ programs.
A printer on the Apple ][ must always be connected via a printer interface card. When you want to use the Epson printer, insert an emulated Grappler+ card in any slot (traditional was to use slot #1) and connect the Epson printer to it. Read the section on Configuration for more information on how to do this.
The emulation supports most of the functions of the original printer, such as different character pitches, bold, italic and underlined text, margins, tabs, and graphic modes. Actually the only feature not supported is printing proportional characters.
The technology used by the emulator for text rendering is very different from the technology used in the original Epson. As a result, the characters are somewhat different, but the size and looks of the characters are just like the real thing, as this example shows:

Apart from all Epson built-in character types, the emulation is also able to print graphics. This allows you to run a program like Broderbund's PrintShop.

Using the Epson printer is straightforward. While the Apple ][ is printing, the green light on the "Printer" button blinks. When printing has finished, click the Printer button to see a preview.

While the preview is open, the printer is offline, so the Apple ][ will hold new output. The printer comes back online when the preview sheet is closed.
The preview shows the printed output on one or more pages of fanfold paper. The length of one page can be chosen in the Printer section of the Configuration panel, and is 11 inches by default.
Two blue triangles, on the left and right hand side of the paper, indicate the "current position": this is where the next line of output will appear.
At the bottom of the sheet are a few buttons:

- Leave in Printer: pressing this button closes the preview sheet without affecting the output.
- Tear Off and Save: this button saves the print output in a pdf file. It then clears the print output from the preview and closes the sheet. So metaphorically this is like tearing off the fanfold paper and storing the output in a safe place.
- Tear Off and Delete: this clears the output without saving it and closes the sheet.

After saving the output to a pdf file you can use Apple's Preview program or Adobe Acrobat Reader to view the output or print it on a real printer.

The "Action" menu in the preview sheet contains a number of special options.

- Skip Page is like the "Form Feed" button on the real Epson: it skips to the top of the next page.
- Skip Line moves the paper forward one line, like the Line Feed button on the original printer.
- Auto Linefeed toggles the printer between two modes. When "Auto Linefeed" is "on", every carriage return character also advances the paper one line; when it is "off", carriage return just moves the print head to the left margin. Normally, the printer interface card takes care of generating the appropriate control characters, and therefore the recommended setting is "off". When you find that the Apple ][ software prints all lines on top of each other, try switching this option on and print again.
- Use 8th Bit is another technical option. When it is activated, all 8 bits of every byte are sent to the printer; when switched off the high order bit of every byte is ignored. This option should normally be off.
- Hex Dump Mode puts the printer in a special state: all output is printed as hexadecimal numbers. This option was often used on the Epson printer for debugging purposes. Note that changing this option clears the print output and closes the sheet.
- Reset Printer puts the printer in the initial state, as if it were just switched on. It also clears the print output and closes the preview sheet.

The Printer section of the Configuration panel lets you set additional printer options, corresponding with the "DIP switches" in the original printer.

#### The ImageWriter II printer

From a user perspective, the ImageWriter II is very much like the Epson FX-80. Both are capable of printing text in different styles, and both can print graphics. From a technical perspective however, the printers are quite different. As a result, some Apple II programs are compatible with just one of these printers. For example the "MousePaint" program, which came with the Apple Mouse, can only print on the ImageWriter, not on the Epson.
The ImageWriter II printer must be connected via a serial interface card. When you want to use the ImageWriter II, insert an emulated "serial printer card" in any slot (traditional was to use slot #1) and connect the printer to it. Read the section on Configuration for more information on how to do this. Note that the serial printer card is actually the Apple super serial card, pre-configured to be used with this printer.
The ImageWriter II did have a unique feature, not found in the Epson, namely the ability to print colors when a color ribbon was installed. This feature is fully supported by Virtual ][.
The ImageWriter II allowed the user to select three different print qualities: draft, correspondence, and near letter quality (NLQ). The emulation only supports the "correspondence" setting, which is the most versatile and has less restrictions than the other two. Note that text is printed with the Macintosh font rendering engine, which in practice gives even better results than NLQ on the original printer.

Operating the ImageWriter in Virtual ][ is identical to operating the Epson priner, so refer to the previous section for details.

#### The simple "text only" printer

This printer can be connected to either the Grappler+ or the serial printer card. It writes all printed output to an ASCII text file. When printing is finished, or even during printing, you can open the file and process it in whatever way is useful. The name of the printer file is of the form "Printer x - slot y.txt". In this name, x is simply a number starting at 1; y is the slot number the printer is connected to. All printer files are created on the desktop; the location cannot be configured. If a printer file with the same name already exists, new printed output is appended to the end of the file, so in effect the printer file is like an infinite supply of fanfold paper. When a virtual machine is closed the corresponding printer files that are still empty are removed, so the desktop will not be cluttered with empty files.

The easiest and safest way to inspect the printed output is by clicking the "Printer" button in the devices drawer. First, this button places the emulated printer in the "offline" state, so the Apple ][ will hold new output until the printer goes online again. Next, the corresponding output text file is opened in TextEdit. To continue printing, close the text file and press the "Printer" button to put the printer online again.

#### Printing to the Macintosh clipboard

You can temporarily override the current printer by selecting "Print to Clipboard" from the Edit menu. While this mode is in effect, all printed characters go to the Macintosh clipboard, so they can be pasted in a text editor or word processor after printing has finished. Be aware that clipboard printing is only intended for ASCII text output. This makes it ideal for making a text copy of an Applesoft Basic program; first list it to the clipboard printer, then paste it into a Macintosh text editor. The "print to clipboard" mode is terminated by selecting the same menu option again.

###

The serial interface

#### Introduction

In the early 80's, a serial connection was an inexpensive, simple, and therefore popular way to connect the Apple II to another computer. This could either be a local computer, directly connected with a serial cable, or a remote computer, accessible via a modem. There was no such thing as the Internet back then, but a network of bulletin board systems (BBS's) existed that allowed their members to log on using a modem (typically 1200 baud, sometimes even slower).

#### Serial port emulation

Virtual ][ emulates the Super Serial card (SSC), which was produced by Apple and was the de facto standard for serial communication on the Apple II. This card implemented the universally accepted RS-232 standard.
The SSC emulation can be configured to connect to a real serial connection on your Macintosh. Even though Macs don't come with a built-in serial port anymore, there are still several ways to use this medium. One option is a USB-to-serial adapter; another one is a built-in modem; and a third option is Bluetooth. The Virtual ][ configuration panel presents you with a pop-up menu that contains all serial devices available on your Mac. Exactly what it shows depends on your hardware configuration, but here is an example of what it could look like.

In this example, the top three menu items belong to a USB-to-serial adpater; the next two represent a Bluetooth connection to a mobile phone. The two entries below the separation line are built-in modems.
If you have Bluetooth in your Mac and in your cell phone, you can use an Apple II communication program to actually talk to it; for example, issuing the command "AT+CGMI" causes the phone to return its manufacturer's ID.

#### Configuring the serial connection

Configuring the serial communication setup requires some patience, just as with the original Apple II. There are three areas to take into account: the DIP switches on the Super Serial card, the device connected to it, and the Apple II software.

The DIP switches on the SSC control a number of customizable options like the baud rate at power-on. These options can be configured in a separate window, by pressing the "Configure..." button below the picture of the SSC in the main configuration panel.

You cannot manipulate the DIP switches with the mouse; instead you can select options with the buttons, and you'll see the switches move accordingly. Note that many of these settings can also be set by the Apple II software, which is actually more convenient than setting the DIP swiches and restarting the virtual machine. The options that can not be changed by the Apple II software are communications / printer mode and interrupt mode. When the latter is selected the SSC triggers an interrupt when data is sent or received, in order for the Apple II to deal with that event immediately. Only activate this option if you know the Apple II software supports it!
Note that some of the DIP switches cannot be changed at all; they must have a fixed setting in order for the emulation to work properly. In particular, Virtual ][ does not support the old Apple serial interface modes of the SSC.
Note further that switch 8 is a dummy on both banks; it has no function.

The second area to worry about is the Macintosh device connected to the SSC emulation. Note you can select this device and the associated options without the need to restart the virtual machine.

These checkboxes correspond to three special signals the SSC can receive: Data Set Ready, Data Carrier Detect, and Clear To Send. These signals all tell something about the status of the connected device. For example, the DCD signal is generated by a modem when it has a connection, over a phone line, with another modem. This is a very useful signal for an Apple II program that waits for an incoming call: when DCD is activated, the program knows someone made a dial-up connection.
Unfortunately, due to a lack of strict standards, some Apple II programs interpret these signals in a different way. For example, the firmware of the SSC only sends a character when it detects that the DCD signal is ON. This effectively prevents the program to send a dial-up command to a modem! With the original Apple II this was solved by connecting the DCD line to another line, to ensure it was always ON. This same technique is supported by Virtual ][: checking a box in the configuration panel sets the corresponding signal to ON.
Also, not all serial devices generate these signals. Usually the Apple II software will verify the DSR signal, which indicates that the connected device is powered on. However, when the other device does not generate this signal, or when the line is absent from the serial cable, the only option is to force the signal to be ON.
The CTS signal is used for hardware handshake and should usually not be forced ON.
More information on these signals can be found in Wikipedia.

The "asynchronous send" option controls a timing aspect. When the option is turned on (the default), Virtual ][ forwards each outgoing byte to Mac OS X, and immediately allows the Apple II to send the next byte. Meanwhile, OS X sends these bytes whenever it has the opportunity to do so, in other words: asynchronously. As a result, there can be some delay between the Apple II sending the byte and Mac OS X actually delivering it to the device at the other end of the line. Usually this works fine, and this approach results in a throughput that is almost identical to the original Super Serial card.
However, there are circumstances where the asynchronous approach fails. For example, consider a situation in which the Apple II sends characters to a printer, and pauses after each "newline" character, in order to give the printer the opportunity to move the paper. In that case, the asynchronous mode would not work, because the Apple II must pause after the newline character has been received by the printer (and not after the character has just been sent by the Apple II program). The only way to accomplish this, is to use the synchronous mode: the Apple II will not send the next byte until the current byte has been delivered to the other side.
Note that synchronous mode causes overhead and considerably slows down the output stream.

As a last step of your configuration efforts, the Apple II software must be set up to match the selected emulated hardware options. Most applications offer the Super Serial card as one of the standard configuration options.
When you want to use a modem, and the modem you use is not listed in the program's configuration options, the best guess is to configure it as a "Hayes compatible" modem. Also, choose a moderate baud rate; 1200 or 2400 baud are speeds typically used in the Apple II days. When it all works, you can try to increase the speed.

#### Monitoring the serial connection

When you have a Super Serial card installed, Virtual ][ shows a status panel in the devices drawer. The panel shows the status of the RS-232 signals, and can be a great help in troubleshooting. The signals are described in this Wikipedia article. When a signal is OFF, it is shown in dark red; when a signal is ON (or "asserted"), it lights up. The signals are presented as seen from the standpoint of the Apple II, so "RD" indicates the Apple II receives data, and "TD" means the Apple II is transmitting data.

The signals on the left are input for the Super Serial card; the signals on the right are output. You can click on the button to get a pop-up menu that gives the same options as the configuration panel: you can force any of the input signals to be ON, and you can select (a)synchronous send mode.

If you are familiar with the RS-232 standard, you might notice that the signal "RI" (Ring Indicator) is missing in the status panel; the Super Serial card does not support it.

###

Using the cassette recorder

#### General description

The cassette recorder emulation is able to record a file with the sounds produced by the Apple ][ cassette output, and also to read such a file and feed it to the Apple ][ cassette input. Effectively, this provides a fully functional cassette tape emulation. The cassette tape files are actually standard AIFF files. If you are curious how they sound, you can open a cassette tape file in the Quicktime player. Note that you might have to change the file name extension from "cass" to "aif" for Quicktime to recognize the file. It is recommended to turn down the volume a bit, because the sound is loud and ugly.

It is even possible to sample an original Apple ][ cassette tape and read it in the emulator. Refer to "Format of the cassette tape file" for details.

Remember that the main purpose of the cassette tape support is nostalgia. It is much more practical to store data on an emulated disk, because the cassette files can become pretty big and the I/O is time consuming.

#### Playing a cassette tape

To "play" a cassette tape, it is sufficient to "insert" the cassette tape file in the cassette recorder. This can be done in a similar way as inserting a disk in a disk drive: either click the appropriate media button and select a file, or drag the file from the Finder to the cassette recorder icon in the devices drawer. The cassete recorder icon will show a "Play" symbol, but actually the tape starts playing when the first sample is read by the Apple ][ software. So there is no hurry to start the Apple ][ software that reads the tape, even if the tape is inserted first.

You can try this using the "Welcome tape" distributed with the program. It contains a simple Applesoft program. First make sure you see the Applesoft prompt ("]"), then type "LOAD" and press return. Now insert the tape as described. Reading the tape takes about 30 seconds. When the prompt shows up again you can type "RUN" to run the program just loaded.

To eject the cassette tape click the cassette recorder icon.

#### Recording to a cassette tape

It is not possible to overwrite an existing tape file. To make a recording, create a new tape by clicking the "New cassette tape" icon in the devices drawer and specify the name of the tape in the file save panel that appears. The cassette tape icon shows a "Recording" symbol, and recording starts right away, so the first few seconds of the recording are probably silence. Note however that after the Apple ][ software has produced the last sound sample, no more silence is recorded, so there is no rush to remove the tape after recording has finished; the file won't grow more than necessary.

#### Format of the cassette tape file

If you want to try sampling an actual Apple II cassette tape, you'll need to know the exact file format:

- The file has to be uncompressed AIFF; no audio compression is supported.
- Sample size can be 8 or 16 bits. However, 16 bits does not provide an advantage over 8 bits, because the Apple ][ accepts only 8 bit samples. When writing a cassette tape, the emulator outputs 8 bits per sample.
- Sample rates up to 64000 Hz are supported. High rates give more reliable results than low rates. When writing a cassette tape, the emulator uses a sample rate of 16000 Hz.

When reading such a sample in the virtual machine, you might end up with "ERR" displayed on the screen. If this happens, the emulated software did detect a signal (which is good), but was not able to read all data. In this case, try a few different settings for the playback volume slider. You'll find it in the "Cassette interface" section of the configuration panel.

Note that the entire file is kept in memory as long as the cassette tape is in use.

###

Using the 80-column card with the Apple ][ and Apple ][+

Note this chapter is only applicable to the Apple ][(+). For the Apple //e, see "Using 80-column display on the Apple //e ".

#### Selecting 80-column video or built-in video

The Virtual ][ emulator has the option to present 80-column text video by inserting an emulated 80-column card in slot 3. Note that the card does not work in any other slot! The 80-column card contains its own video generator circuitry, and is connected to the video monitor through a "video soft switch". This switch has two inputs, and one output. The internal video generator and the 80-column card are connected to the inputs, and the switch forwards one of the signals to the video monitor. It looks at the state of annunciator #0 to determine which signal to forward. A reference to address $C058 selects the primary input signal, and $C059 selects the secondary input signal. Furthermore, Virtual ][ contains configuration options to choose which video generator is primary and which is secondary. The next picture summarizes the different options:

In the picture, "Show Built-in" and "Show 80-col." refer to choices in the "Quick settings" menu.

#### Selecting the 80-column card for keyboard input

As the 80-column card is in slot 3, "PR#3" will shift input and output to the card. Or when you start the UCSD Pascal system, it determines the card automatically and switches I/O to it. In all cases it is still necessary to direct the 80-coumn video output to the monitor as described above.

The 80-column card supports the full ASCII character set (upercase and lowercase). In order to work correctly, the "shift key modification" must be applied. You'll find this setting under the keyboard configuration. The "shift key modification" in the original Apple ][ involved connecting pin 2 of the keyboard encoder board to push button 2 (pin 4) of the game I/O connector. This modification allowed the software on the 80-column card to detect whether the shift key was pressed in combination with any of the other keys.
Note that in order to enter lower case letters, "Soft Caps Lock" must be turned off in the "Quick settings" menu.

#### 80-columns card special characters

When the keyboard is correctly configured for use with the 80-column card, all characters can be entered in the normal way, except two: when you enter "^", the 80-column card translates it to "N". Likewise, it translates "@" to "P". This is a result of the original Apple ][ keyboard layout. These two characters must be entered with the "ctrl" key pressed.

Also, the 80-column card has a few interesting special key combinations. The below table summarizes all special key combinations.

ctrl-shift-^ | Enter the character "^"
ctrl-shift-@ | Enter the character "@"
ctrl-shift-E | Inverse mode
ctrl-shift-C | Normal (non-inverse) mode
ctrl-shift-D | Make hardcopy of the screen on the emulated printer.
ctrl-shift-A | Toggles the soft caps lock of the 80-column card. This is basically the same as the soft caps lock of the emulated keyboard (command-shift-A). You can use either option to enter lower case characters.

###

Using 80-columns display on the Apple //e

The Apple //e has built-in 80-column software support. The only additional thing needed is a memory card in the auxiliary slot. By default, such a card is present in a newly configured virtual Apple //e. It allows 80-column display, double-hires, and adds 64K of memory to the machine, bringing the total amount of memory to 128K. Note that this card can be configured to contain more memory (up to 8MB).

The Apple //e contains only one video generator, which is used to produce either a 40-column display or an 80-column display, so no "video switcher" component is used, like in the Apple ][.

###

Using the AppleMouse

Virtual ][ emulates the AppleMouse // card. This allows you to run programs like MousePaint or GEOS.
Apple II software that uses the mouse must switch it "on" in order to become active. When this happens, the Macintosh mouse pointer is hidden, and replaced by whatever mouse pointer the Apple II software provides.

The mouse emulation is designed to smoothly integrate with the Macintosh mouse: when the mouse pointer enters the window, it instantly turns into the Apple II mouse, and the Macintosh mouse pointer is hidden. The reverse happens when the mouse moves out of the window: in that case it becomes a Macintosh mouse pointer again.

#### Relative mouse mode

Unfortunately, integration with the Macintosh mouse is not compatible with some Apple II programs. It is compatible, for example, with MousePaint, but it doesn't work wel with GEOS. To solve this problem, the mouse emulation supports a special mode of operation: "relative mouse mode". You'll find it in the "Quick settings" menu. When this mode is switched on, programs like GEOS work well, at the expense of Macintosh mouse integration. Once the mouse has entered the window, it will be captured there, and you must hold down the command key to let it escape.

###

Using the real time clock

The Apple ][ was not equipped with a built-in real time clock. Several extensions existed to provide a clock, and Virtual ][ emulates three of them.

- The Mountain Computer AppleClock card can be used with DOS in the Apple ][ and Apple ][+ computers. It cannot be used with the Apple //e or with ProDOS.
- The Thunderclock Plus card can be used on any of the machines. After its introduction in 1980 it became the de facto standard for the Apple II computers, and it is well integrated in ProDOS. It is recommended to insert this card when you run ProDOS, because the operating system then automatically uses it to time stamp your files.
- The "no-slot clock" is a clock chip that fits underneath a ROM chip in the Apple //e. It was a popular option, because it provides a real time clock without occupying a slot. To use it, a software driver must be installed on the ProDOS boot disk.

The emulated clocks take the current time and date from the Macintosh clock. Only the Thunderclock emulation allows adjusting the date and time; the others do not. However, when you reboot the virtual machine, or create a new one, the Thunderclock will always be reset to the Macintosh system clock. Changing the Thunderclock time does not affect the Macintosh clock.

###

Using the Z80 card and CP/M

A popular enhancement for the Apple ][ (and //e) computers was the Z80 card. This card contains a Zilog Z80 or Z80A processor, plus hardware to transfer the flow of control from the main 6502 processor to the Z80 and vice versa (only one of the processors can be active at any time). The Z80 card made it possible to run the CP/M operating system, and gave access to popular applications like Wordstar, DBase and Supercalc. It also allowed the use of programming languages like Turbo Pascal, Fortran, and even COBOL.
The Z80 card in Virtual ][ emulates the Z80A processor. You can configure the processor to run at a speed of either 2 MHz or 4 MHz.
To use the card you need a bootable Apple ][ CP/M disk image. The boot software on this disk searches for the presence of a Z80 card. When it detects one, it switches to the Z80A processor. After booting is complete, the CP/M prompt is presented.

###

Using the joystick / game paddles

The original Apple ][ came with two game paddles. Each paddle provided an "analog" input by turning a knob, and a "one-bit" input by pushing and releasing a button. A popular enhancement was to replace the two paddles by one joystick.
The Game I/O connector of the Apple ][ allows for connecting 4 analog inputs and 3 one-bit inputs. All of these can be emulated by Virtual ][, either with the Macintosh mouse and keyboard or with a game pad / joystick connected to a USB port. Virtual ][ will always use the USB game controller when it detects one.

#### Emulating the game paddles with a USB game controller

The program automatically selects this method when it detects a suitable game controller connected to a USB port. You can specify the mapping between buttons on your game device and the Apple ][ game inputs by selecting "Configure Game Controller" from the "Virtual ][" menu. In the dialog that appears you can select a game device button or slider and link it to a corresponding Apple ][ input, such as "Paddle Analog #0", or "Paddle Button #1".

The dialog will probably appear in the non-graphical mode (as shown on the right), unless you happen to have a Wingman Rumblepad, in which case a picture of the device is presented (as shown on the left).
Two special actions can be assigned to buttons on the game device: "Pause / Resume" and "Pause and Configure". The first one pauses the entire virtual machine, and therefore is useful to temporarily suspend game play. Pressing the same button resumes the game. The second option pauses the virtual machine and shows the game controller configuration panel. This is useful when you want to try different settings for a specific game.
Note that the game controller mappings are part of the overall configuration of Virtual ][, not just of one specific virtual machine configuration. The game controller settings are automatically saved.

#### Emulating the game paddles with the keyboard

Virtual ][ lets you control the game paddles with the keyboard as well. In the configuration of the game connector, you can activate the arrow keys to be used as a joystick. This works fine for many games, but be aware that it does not give you the same amount of control as a real joystick does. A real joystick produces values between 0 and 255 for the horiontal and vertical directions. With the keyboard arrows, the possible values are limited to only three: 0, 128, and 255.

You'll find the "Game connector" configuration panel in the "Built-in connections" section of the machine configuration.

Technically speaking, the left / right arrow keys control game paddle number 0, and the up / down keys control paddle number 1. When you notice that pressing the "up" arrow actually moves your game character down, click the "Flip vertical motion" checkbox.
The emulated joystick is self-centering; when you release the arrow keys the joystick position goes back to the center.

As a shortcut to activate the arrow keys, you can also select "Use Arrows as Joystick" from the "Quick settings" menu.

The push buttons on the paddles can be controlled by the mouse buttons or the keyboard modifier keys: control, alt and command. It is recommended to assign the control key to push button 0, and to avoid the use of the command key during game play.
Note that push button #2 is not available if it is being used in the "shift key modification", required for the Apple ][(+) 80-column card.

#### Emulating the game paddles with the mouse

As a third option, you can use the mouse to control the analog game paddle values. However, because Virtual ][ cannot detect mouse movements outside its window, this feature works only when the program runs in full-screen mode. Furthermore, it is disabled when a USB game pad or joystick is connected.

This mode of operation is automatically selected when Virtual ][ doesn't detect a suitable USB game controller. The analog values depend on the position of the mouse on the (main) screen.
Note that when an Apple II mouse card is inserted and switched on, the Macintosh mouse only feeds the emulated Apple II mouse, not the game paddles.

The push buttons can be controlled with either the mouse buttons or the keyboard modifier keys, as explained in the previous section.

###

Working with sound

#### Overview

Sounds played an important role in the Apple ][ computer. First of all, it had an internal speaker, controlled by the software. It could do more than just produce simple "beep" sounds; many games used the mechanism to produce music and sound effects. Secondly, there were the sounds produced by the hardware. Everyone who used an Apple ][ knows the "clackety-clack" sound of the disk drive when you booted the operating system. Finally, you could increase the sound capabilities of the machine with third party hardware; the most popular was the Mockingboard card.
Virtual ][ supports all these options; they are described briefly below.

#### Internal speaker

The internal speaker is the device that produces the "beep" sound when you switch on an Apple ][. In the emulator, you'll hear the sound on the Macintosh loudspeaker (or external speakers if you installed them). The original machine had no way to control the sound volume or to switch off the sound. However, the emulator does. In the toolbar you'll find a control for it.

#### Sounds produced by the hardware

Virtual ][ is able to produce a number of these sounds, all recorded from original hardware. The preferences panel contains checkboxes to switch on and off the different sound effects. By default they are all switched on.

#### Mockingboard

The Mockingboard card was able to produce much higher quality sounds than the internal speaker. It came in different flavors; the one supported by Virtual ][ emulates two sound chips that together can produce 6 simultaneous sounds. The Mockingboard card is used in some popular games, like Ultima V. When the Apple ][ asks you to identify the card, specify type "A", or "Sound II".

###

Using different screen sizes

#### Setting a screen size

The size of the main window can be adjusted with the "Screen" menu. You can choose single size, 1.5 size, or if your Macintosh display allows it, double size. By default Virtual ][ presents the screen in single size, but you can change this behavior with the "View" section of the application preferences.

#### Using full-screen

Full-screen mode makes the emulation even more realistic. In full-screen mode the screen of the frontmost virtual Apple ][ is presented on the main (or only) Macintosh display. You can easily switch between window-mode and full-screen mode with the key combination "command-enter".

As an option, the program can adjust the resolution of your Macintosh screen in full-screen mode, so that it closely matches the resolution of the Apple ][ screen. This has the advantage of improving performance, in particular on big screens. If your machine can handle the load, it is recommended to leave the screen resolution as it was; the rendered image will look much better.

In full-screen mode it is not possible to operate the buttons in the devices drawer or switch between different virtual machines.

#### Use of the command key in full-screen mode

In full-screen mode on an Apple ][(+) you can use all keyboard shortcuts in the "Quick settings" menu, which includes switching between color and monochrome, and switching between 40-column and 80-column display. You can also use command-I to insert a new diskette: the emulator temporarily switches to window-mode and switches back to full-screen after a disk image has been selected.
However, when in full-screen mode on an Apple //e, the command key is used as "Open Apple" key. Macintosh keyboard shortcuts won't work, except for command-enter to go back to window-mode.

###

Recording a movie

Virtual ][ lets you easily record a QuickTime movie of everything that happens on the emulated Apple II screen. Just select "Make Movie of Apple II Screen" from the File menu. The program will present a standard File Save panel to let you select where the movie must be saved. After that, recording starts, and will continue until you select "Stop Movie Recording" from the File menu. After recording has stopped, the movie will automatically be opened in the QuickTime movie player.

If you pause the virtual machine, movie recording also pauses. It continues when you resume the virtual machine.

During recording, the movie is written to a temporary file on your disk. When you stop recording, the temporary file is moved to the location you selected. This might take a few seconds.

Virtual ][ records the movies at 20 frames per second. To do this alongside the running emulator requires a lot of CPU power. However, a modern Intel-based Macintosh can handle this. On an older machine, such as a PowerMac G4, you might notice a decreased frame rate.

The movies recorded in Virtual ][ typically take 3 to 6 MB of disk space per minute. If you want, you can reduce the file size later on, by opening the movie in the QuickTime player, and exporting it with a high compression codec such as H.264. This may take a while, but can reduce the size of the movie considerably.

Note that the movie recording option is only available in the full license version of the program.

###

Working with character sets and international keyboards

#### About character sets

The computer's "character set" is the collection of all characters that can be displayed on the text screen. The US model of the Apple II computer was equipped with the standard ASCII characters, but international models usually had an alternative character set, with characters for specific languages. For example, the French model supported characters like à, é, and ç. Because the character coding space was limited, these characters replaced @, {, and \, respectively.
The international Apple II machines came with a switch that allowed the user to instantly switch between character sets. The same functionality is available in Virtual ][. The "Quick settings" pull-down menu contains a list of available character sets.

By selecting a character set, some of the characters on the screen immediately change. This example shows how the Apple //e welcome line is shown in the Latin character set and the Greek character set, respectively.

#### About international keyboards

International Apple II computers supported international characters, both on the screen and on the keyboard. To that purpose they were equipped with a special character generator rom that defined both the international and the standard ASCII characters. For example, on a French keyboard you could press the key labeled é, and if the French character set was selected, an é would actually appear on the screen.
Selecting a character set in Virtual ][ results in showing the characters from that set to be shown on the screen, and at the same maps the special characters on your Macintosh keyboard to the equivalent Apple II character code. So for example, if you have a French Macintosh, and you set Virtual ][ to the French character set, pressing the key labeled é will also produce an é on the screen. However, if you select the "Latin" character set (the standard ASCII characters), pressing the same key will not produce a character on the screen.
Because the keyboard behavior obviously depends on the currently selected character set, you'll see a little flag symbol at the top left of the window to remind you what the current setting is.

#### Character sets in Virtual ][

The program comes with a number of predefined character sets, as shown above. The character sets "Latin" and "Latin Uppercase Only" are the ones representing the standard ASCII characters. The "uppercase only" variant was used in the Apple ][ and the Apple ][+, because these machines lacked lowercase character support. The "Latin" set was standard in the Apple //e, and contains all ASCII characters plus a number of special characters (the so called "mouse characters", used to draw user interface elements such as window borders).

Note that the Bulgarian character set is based on the Pravetz-82 (Правец-82), a popular Apple ][ clone. The character set works best when you install the Pravetz-82 system ROM.

#### Defining your own character sets

In the Apple II computer the characters were defined in a character generator ROM, which could be replaced by a customized ROM. Virtual ][ offers the same feature. In order to do this, you must provide the program with the following:

- A bitmap file with the character definitions. The format of this file is described below.
- Optionally, a bitmap with a picture of the "flag" symbol to be shown at the top left of the main window when your character set has been selected. If you omit this, no symbol will be shown.
- Optionally, a translation table to map keyboard characters to your character set. If you omit this, no translation will take place.

The character definition bitmap should be placed in the directory ~/Library/Application Support/Virtual ][/CharacterSets. The file contains pictures of all symbols in the character set, and must be structured as follows:

- The file must contain a bitmap saved as Tagged Image File Format (TIFF).
- The width of the bitmap must be exactly 128 pixels.
- The height of the bitmap must be at least 64 pixels.
- The depth of the bitmap must be 1.
- Each character of the set is defined in a cell of 8 x 8 pixels. This implies that the entire character definition bitmap contains 8 rows of 16 characters each. Note that the rightmost pixel column of each character cell is ignored, because characters on the Apple II computer are actually 7 pixels wide.
- A pixel value of 1 in the bitmap represents "black", and is part of the background. A value 0 represents "white", and is part of the character.
- The first two character rows of the bitmap define the symbols of the "alternate" character set on the Apple //e computer. Their ASCII values range from 64 to 96, and these characters are shown if the alternate character set has been activated by the Apple II software. These symbols are ignored on the Apple ][ and the Apple ][+.
- The 3rd to 8th rows of the bitmap define the characters with ASCII values 32 to 127.

As an example, here is the definition file of the character set "Latin", used in a standard Apple //e.

The second element of your own character set, the "flag" symbol representing the character set, can be any picture format Mac OS X is able to read. It is recommended to use the tiff or png format. For best results, make the picture at most 11 pixels high and at most 16 pixels wide. The picture must be stored in the same directory as the character set definition file.

The individual files, along with the keyboard translation table, are tied together in an XML file with this path: ~/Library/Application Support/Virtual ][/CharacterSets/International.plist.
It is recommended to create such a file with the "Property List Editor" program. It's format can best be explained by showing an example.

This example contains two custom character defintions, named "My character set" and "Yet another character set". These names will appear in the Character Set menu. If you choose a name already in use by a built-in set, your definition replaces the built-in one. So if you want to add a new character set, be sure to choose a unique name.
Each character set entry is itself a dictionary with three elements: the name of of the character set definition file, the name of the associated icon file (the "flag" symbol), and the keyboard translation table. You can leave the icon file name empty if you don't want to assign one.
The keyboard translation table contains two columns: the first is the character typed on the Macintosh keyboard; the second is the resulting ASCII code (in the range 0 - 127) that will be input in the virtual machine. You can specify the second column value as either a number (the ASCII value) or as a string (the actual character). The first column must be one single character, and it must not be in the standard ASCII range. So for example, you cannot translate the character "a" to something else, nor can you translate a control code or a function key. You can, however, translate non-ASCII characters, as shown in the example.

###

Configuration

#### Overview

Virtual ][ has many configurable options. Different virtual machines can have different configurations. The configuration can be saved using the "Save Configuration" choice of the File menu. Use the "Open..." choice of the File menu to create a virtual machine from a saved configuration (or simply double-click a configuration file in the Finder).

To change the configuration of a virtual machine, choose "Configure..." from the Machine menu, or click the "Setup" button in the toolbar. The configuration of the current machine is presented in a sheet, like this:

The configurable options are presented in the left pane, in a hierarchical way. When you click on a configurable item, the right pane shows that item's configuration options. You can change one or more configuration options and then press "OK" to change the configuration of the virtual machine. Some changes can be made without restarting the machine (like changing the monitor from monochrome to color); other changes require a restart. If you make a change that requires a restart, a warning is shown at the bottom of the configuration sheet. Note that if you want to save the modified configuration, you have to choose "Save Configuration" from the File menu. Virtual ][ will remind you if you close the window without saving.

#### Quick settings

Some of the configurations can also be changed with the "Quick settings" menu. It deals with properties of the monitor and keyboard, and provides an quick way to change them. The changes made with this menu don't mark the configuration as "changed", so if you close the window you will not be reminded to save the document. However, if you save the document, the current quick configuration settings will be saved with the configuration.

#### Checking the performance of the virtual machine

To see if the virtual machine runs fast enough on your Macintosh, choose "Show Performance" from the Machine menu, or click the "Speed" button in the toolbar. It reveals a drawer with performance statistics, like this:

The presented minimum, maximum and average CPU statistics are measured starting at the moment the drawer opened, and are relative to the nominal CPU speed. So if "average" is 100%, the virtual machine runs exactly at the intended speed.
"Current" is the speed (in MHz) of the currently active processor. When the internal 6502 (or 65C02) is active, the number is presented on a red background; an orange background means the Z80A processor is currently active. This speed is also represented by the red / orange line in the graph. The yellow number and yellow line represent the number of screen refresh cycles per second.
Wen the CPU speed drops below the nominal speed, the program tries to compensate the speed, in order to end up with an average of 100%. However, if the video refresh rate drops too low it is not compensated (as this would be a waste of processing power).
Note that when you are running CP/M (and thus using the Z80A processor), you will still see a lot of 6502 activity in the performance monitor. This is caused by the fact that the CP/M BIOS is implemented by 6502 functions (in the Apple ROM, for example). So all I/O is handled by the 6502.

###

Controlling Virtual ][ with AppleScript

#### Overview

Virtual ][ supports Apple's powerful AppleScript technology, which allows you to control the virtual machine using a script. The script can do such things as create and configure virtual machines, type commands on the virtual keyboard, wait until the screen indicates an operation has finished, save printed output, and even insert disk images directly from the Internet. It allows you to let Virtual ][ perform an automated task, such as starting up your favorite Apple II game. You can also use it to create some nice Apple II demo's.
The program comes with a number of example scripts, which you can find in the AppleScript menu.

When you select one of the example scripts from the menu, you will get the choice to either run the script or open it in the Script Editor. The scripts are hidden inside the Virtual ][ application bundle, so if you want to make changes, it is recommended to save them in a different location.

When you make your own scripts, you can add them to the AppleScript menu by copying them to the Virtual ][ scripts folder. The easiest way to locate that folder is to select "Open Scripts Folder" from the AppleScript menu.

#### A practical example

This example shows some of Applescript's possibilities.

Suppose you often play the game "Little brick out", which was distributed on the original DOS 3.3 master diskette. You always play it on an Apple ][+ with a color screen. When you make a script that starts your favorite game in Virtual ][, you only have to double-click that script to begin your game play.
In its most elementary form this is what such a script looks like.

The script assumes that the disk is called "3.3 master.dsk", and is in the folder you configured as your "favorite disk folder" in the Virtual ][ preferences.
The script first moves Virtual ][ to the foreground (activate) and gets rid of any currently running virtual machines. It then creates an Apple ][+ and makes sure it has a color screen. After that, it inserts the disk image into slot 6, drive 1. While the machine boots, the script types the DOS command to run the game: "RUN LITTLE BRICK OUT". Virtual ][ sees to it that the typed characters are buffered until the Apple ][+ is ready to process them (which is after booting is complete).

Although this script works OK, it can be improved by temporarily switching the virtual machine to a higher speed during booting and loading the game. This dramatically reduces the start-up time; from the almost 30 seconds it takes on a real Apple ][, to only a few seconds (depending on your type of Macintosh).

The trick is that the script sets the speed of the virtual machine to "maximum", and resets it to "regular" after the game finished loading. The latter is important: you don't want to play the game at top speed! The script must know when to reset the speed; it does this by looking at the screen with intervals of 0.5 seconds. When the last line on the screen displays "PRESS THE SPACE BAR TO BEGIN....", we know the game has started and the speed can be reset.

#### Writing your own scripts

When you want to write a script, a good start is to study the example scripts. Virtual ][ does not support recording a script in the Script Editor, so you'll have to use the editor to type the statements yourself.
However, if you are familiar with the AppleScript language you'll find it easy to write scripts for Virtual ][. The script dictionary is based on a simple object model. At the top of the object hierarchy is the application object, as in any AppleScript dictionary. The application contains one or more machines. When you make a new machine object, you'll get a machine that is configured like the default configuration, just as when you select "New Default Machine" from the File menu. Another way to create a machine object is by making an instance of one of the classes AppleII, AppleIIPlus or AppleIIe. The third way to make a machine is by opening a saved configuration file. You'll find examples of these techniques in the demo scripts.

Referring to a specific machine occurs just like referring to a document in other AppleScript-aware programs: by number or by name. When you have just one virtual machine running, the easiest way is to just say front machine.

A machine object contains a number of devices. You cannot create these device objects with AppleScript; they are automatically created when you create a machine. You refer to the devices by name. For slot devices, the name is derived from the slot it is connected to. For example, a device connected to a card in slot #1 is called "S1". A disk drive, typically connected to a disk card in slot #6, is called either "S6D1" or "S6D2", depending on whether it uses connection 1 or 2 of the disk card. If you are familiar with Applesoft Basic, these device names should look familiar. Devices that are not connected to a slot have fixed names. For example, the cassette recorder device is simply called "cassette recorder".

To find out the device names currently in a machine, execute a script as shown in the example below.

Each device has a property, devicetype, which indicates what it is: an Epson printer, a hard disk, and so on. This example shows the device types of the same virtual machine as the previous example.

You can find out what is on the machine's screen by using the property screen text or screen picture. The screen text gives a collection of all the lines on the screen. You can examine these text objects to see if the running process has produced screen output. Often it is more convenient to use the alternative compact screen text; this one omits empty lines and strips trailing space characters from the remaining lines. Study the example scripts to see how this can be used.

The screen picture property can be used in the same picture command. This powerful command compares (part of) the screen picture with a previously saved file. This allows you to wait until a running process has rendered a specific picture on the graphics screen. Virtual ][ offers a convenient way to save the pictures to compare to: use "Export Screen Picture" in the File menu.

Waiting for some screen output to appear is typically a combination of two things: testing the condition and using the command delay. The latter is part of the standard AppleScript additions. It suspends script execution for a specified time period, while the virtual machine keeps running. This allows you to test the screen at regular intervals (every second or so). The example scripts demonstrate this technique.

Finally, the dictionary supports a way to enter any key on the Apple keyboard with the type command. It has a number of variants, so apart from typing plain characters, you can also enter control-key combinations, open and solid Apple keys, and other special keys like up and down arrows. If the AppleScript type commands are executed faster than the Apple II can process them (which is very likely) the keystrokes are buffered until the Apple II processes them. So eventually all keystrokes will arrive in the virtual machine and none will get lost.

To find out the details of using AppleScript with Virtual ][, use the Script Editor to open the application's dictionary and study the classes, commands and properties.

###

Getting support

Did you encounter technical problems in Virtual ][? Or perhaps you found an Apple II program that doesn't run, or have suggestions for improvements? Tell me about it by e-mail. When reporting a problem, don't forget to mention what versions of OS X and Virtual ][ you use.

You might also want to check if a newer version of Virtual ][ is available on the web site.

###

Release notes

#### Version 7.3

- The "No Slot Clock" now reports Monday as weekday no. 1. Previously it reported Sunday as day no. 1, which was incorrect.
- Added Applescript properties for better control of the connected devices.
- The application preferences now offer two color schemes for high resolution rendering.
- The Inspector now retains its window positions when the virtual machine is restarted.
- Fixed several layout and font issues in the Inspector.
- "Set Disk Properties" in the Media menu no longer refuses volume numbers 0 and 255.

#### Version 7.2.1

- Fixed an incompatibility of the sound effects with Mac OS X 10.7

#### Version 7.2

- Rewrote the Apple II sound emulation. As a result, the application no longer crashes when a headphone is inserted or removed
- Fixed an issue that crashed the application when waking the Mac from sleep
- Fixed a layout issue in the RAMWorks configuration panel

#### Version 7.1

- Fixed an issue that could cause Apple II screen pixels to be randomly shown or hidden.
- Improved implementation of the "mounted OS X folder" feature to fix an incompatibility with EDASM.
- Some of the Applescript demos didn't work in version 7.0; this has been fixed.

#### Version 7.0

- Updated the program to be fully compatible with Mac OS X 10.8 (Mountain Lion).
- Improved accuracy of high resolution colors by adding emulation of NTSC TV color logic.
- Modernized the appearance of the main window.
- The Inspector can now save a memory dump of the virtual machine to a file.
- Added the Bulgarian character set.

#### Version 6.5

- Fixed an issue where the Mockingboard card could halt the virtual machine (this happened, for example, in Ultima IV).
- Corrected an issue in the "floating bus" screen rendering, thereby improving compatibility.
- Fixed an issue that could cause stray pixels on the emulated screen when switching from 80-column text to low-resolution graphics.
- Improved screen rendering perfomance by using Apple's Grand Central Dispatch technology.

#### Version 6.4.1

Corrected some minor issues that were introduced in version 6.4:

- Double-clicking a disk in the Finder didn't work anymore when Virtual ][ did not run - this has been fixed.
- All pictures in the Inspector Help were missing - this has been corrected.

#### Version 6.4

- Dropped support for Mac OS X 10.5 and the PowerPC processor. The program now requires an Intel Mac running Mac OS X 10.6 (Leopard) or better.
- Added a feature to change the write protection and volume number of disk images.
- It is now possible to configure a 65C02 processor in an Apple ][ or ][+ virtual machine.
- When choosing "Copy as Text" from the Edit menu, international characters on the screen are now correctly copied to the Mac clipboard.
- Improved the quality of the QuickLook preview and thumbnail of a saved state file.
- Some custom character sets were not accepted by the virtual machine - this has been fixed.
- Fixed a number of minor issues, thereby improving the overall stability of the program.

#### Version 6.3.7

- Fixed an issue that could cause the arrow keys to generate incorrect game paddle values if used in combination with the command key.
- Added a convenience menu in "Quick Settings" to easily invert the direction of the up and down arrows when used as a joystick.
- The Mac OS X Finder now correctly recognizes disk images as Virtual ][ files.

#### Version 6.3.6

- The program now accepts "dsk" image files with 41 tracks (the maximum so far was 40).
- A recent Snow Leopard upgrade broke the "Make Movie from Apple II Screen" feature. This has been fixed.
- Cassette tape files now get file name extension "cass" instead of "aif". As a result, the cassette tape icon appears correctly again in Snow Leopard. Old "aif" files can still be read.

#### Version 6.3.5

- Improved emulation of Apple II interrupts; as a result, the program "Publish It" version 4 can now be used with the mouse.
- Corrected an error in the emulation of several 65C02 instructions (particularly TSB and TRB). This enhances compatibility with Apple //e applications.
- Relative mouse mode is now correctly restored from a saved state file. This was an omission in previous versions.
- Fixed a few spelling errors in the Inspector and tool tips.
- Fixed an issue that could cause the text color on the Apple II screen to become white after clicking "Cancel" in the the configuration panel.

#### Version 6.3.1

- If the preferences were set to skip the "save" question, the application crashed when quitting. This has been fixed.

#### Version 6.3

- The program is now fully Mac OS X 10.6 "Snow Leopard" compatible.
- Fixed an issue, introduced in version 6.2, where the video inspector didn't render the text screen correctly.
- Fixed an issue that caused the "open Apple" key emulation to work poorly in full screen mode (in Mac OS X 10.5 "Leopard" only).
- In full-screen mode, the I/O activity indicator sometimes remained visible after I/O activity had ended; this has been solved.
- Fixed an issue, introduced in version 6.2, that could cause Applescript execution to crash the program (in Mac OS X 10.4 "Tiger" only).
- Fixed an issue (in Mac OS X 10.4 "Tiger" only) that prevented the use of the built-in French character set.
- In the configuration window, the character set preview showed a few stray pixels. This has been solved.
- Fixed an issue that could cause a gzipped disk image to be incorrectly renamed when ejected.

#### Version 6.2

- Added power management options to save energy and enhance battery life on a notebook Mac.
- Fixed an issue that caused the game disk "World Karate Championship" to fail while booting.
- The Help menu now contains an item to open an online version of the Help section in a web browser.
- In the Inspector, fixed an issue where two lines in the disassembly could be highlighted at the same time.
- Resuming an original Apple ][ from a saved state file could result in incorrect video settings. This has been solved.
- Clarified some topics in the Help section: printing with a limited license, and joystick emulation with the keyboard.

#### Version 6.1

- The Inspector now lets you modify Apple II memory and CPU registers.
- Corrected several issues in the game paddle emulation, thereby improving stability and general compatibility.
- Fixed an issue with the 6502 decimal mode emulation, which caused some UCSD Pascal programs to crash.
- Fixed an issue with the Epson FX80 emulation; in some cases double-width characters were not rendered correctly.
- Clicking an I/O address breakpoint in the Inspector made it invisible; this has been solved.

#### Version 6.0

- Added a feature that lets you record the action on the Apple II screen as a QuickTime movie.
- Added a new module: DiskIIViewer. It allows the Mac OS X "Leopard" Finder to present Apple II disk images in QuickLook and Cover Flow.
- Improved the quality of high resolution rendering.
- The "Search Disk Images" window now shows the results while typing, just like Spotlight.
- The "Search Disk Images" window now shows all diskette names with the selected file system (it used to omit empty disks).
- Added an Applescript command to make a snapshot of the Apple II screen and save it as a file.
- Added an Applescript command to dump (part of) the Apple II memory into a file.
- A mounted Mac folder (DOS) can now hold up to 200 KB (was 140 KB).
- The numeric keypad "enter" key of the mid-2007 iMac keyboard is now correctly recognized.
- Fixed an issue in the Spotlight module that could cause hdv disk images to be ignored.
- Fixed an issue that caused the program to crash if multiple virtual machines used the same serial port.
- This version requires OS X 10.4 "Tiger" or OS X 10.5 "Leopard". It does not run on OS X 10.3 "Panther" anymore.

#### Version 5.8.5

- Solved an issue (introduced in version 5.8) that caused flickering screen objects in some games (such as Swashbuckler, Bolo and Choplifter).
- Improved the floating bus feature; the intro of the game "Money Munchers" now works as it should.
- The "Search Apple II Disk Images" feature now not only searches for matching Apple II file names, but also for matching disk image file names.
- The Inspector can now show the Apple II screen as it would appear in any graphics mode.
- Substantially improved nibble copy and half-track copy in A2V2, resulting in much more reliable disk images.
- Added a menu to check for newer versions.
- Refined the keyboard mappings to more resemble the Apple II: shift-tab now acts as tab; numeric pad "clear" acts as escape.
- Increased default screen refresh rate from 20 Hz to 30 Hz.
- Fixed an issue that could result in stray pixels all over the screen when switching from text mode to graphics mode.
- Fixed an issue that caused the Saturn memory card to behave like a 16K instead of a 128K memory card.

#### Version 5.8

- The A2V2 utility now supports transfer of Apple II disks containing half-tracks.
- Finished the implementation of the "floating bus", and added an example Applescript to demonstrate this feature.
- Optimized graphic rendering, resulting in lower overall CPU load.
- Improved the compatibility of the Epson FX-80 emulation; it now works with the Fontrix application.
- The Inspector now shows the total CPU cycle count of the emulated 6502.
- Added an Applescript command to slow down text input from a script, and used it to make the included demo scripts easier to follow.
- Solved an issue where the text "Paused" could remain on the screen after a restart of the machine.
- Solved an issue that could cause one disk image to be mounted in multiple drives at the same time.

#### Version 5.7.1

- Added an feature to convert legacy DiskCopy disk images to a format supported by Virtual ][.
- When a newly created diskette image was ejected, the program crashed. This has been fixed.

#### Version 5.7

- Added a "search all disk images" feature to the program that presents all disk images found on the system, and allows fast searching for an Apple II file.
- The emulated diskette drives now allow inserting a diskette image in gzipped form.
- The Spotlight search module now also scans gzipped diskettes.
- Solved an issue that caused the emulated game paddle button #1 to "stick" when controlled with the right mouse button or the alt key.
- The previous version (5.6) had introduced a problem with USB game pads on Intel Macs. This issue has been solved.
- Solved an issue that prevented the use of reset (ctrl-F12) in full-screen mode.
- Solved a ProDOS compatibility issue concerning the Thunderclock card.
- Solved an issue that could cause the Inspector to show a wrong memory bank in the slot 3 memory space on an Apple //e.

#### Version 5.6

- Added full implementation of the Super Serial card, allowing an Apple II program to connect to an actual serial device, such as a dial-up modem.
- When the application is started for the first time, it now adapts the window size to best match the computer's main screen.
- Solved an issue that caused ProDOS to fail when formatting a diskette.
- Solved an issue that could cause the program to crash when restarting a virtual machine.
- In very rare circumstances a modified diskette image was not saved when it was ejected. This has been fixed.
- Solved a minor issue with the print preview button; double-clicking while the print preview was open made the presented output invisible.
- In the previous release, one of the ImageWriter pictures was missing, resulting in a blinking icon in the devices bar while printing. This has been corrected.

#### Version 5.5

- The arrow keys on the keyboard can now be used as a joystick.
- The "enter" key on the numeric pad can now be used as an alternative "return" key. This is consistent with the numeric key pad of the Apple //e.
- Improved ProDOS compatibility of the Thunderclock emulation.
- Fixed a potential crash when the virtual machine is restarted.
- Fixed yet another issue with license key validation when Japanese is the system default language.
- Reorganized the long list of subjects in the documentation, in order to make it more accessible.

#### Version 5.4

- Added emulation of the Thunderclock card, and made it the default clock card for all virtual machine types.
- The old "ProDOS clock card" is now obsolete. It is still supported, but can no longer be selected in a new configuration.
- Added emulation of the the Saturn 128K memory card.
- Improved the support for international keyboards.
- Added additional Apple II character sets: British, French, German, Itialian and Swedish.
- Adjusted the Apple //e character set, to eliminate some minor differences with the characters in the original machine.
- Added an AppleScript property to get the path of the configured favorite disk folder.
- The RAMWorks card can now be configured in increments of 64KB (was 128KB).
- The 16K RAM card can now be inserted in all slots, not only slot 0.
- Fixed an issue that prevented 2img disk images from being recognized on an Intel Mac.
- The "generic printer card", which has been obsolete since version 3.4, is no longer supported. It has been replaced by the Grappler+ card and the serial printer card.

#### Version 5.3

- The program can now be controlled with AppleScript.
- Added an AppleScript menu with a number of example scripts; they demonstrate many of Virtual ]['s features.
- Added a menu function to save a snapshot of the emulated screen as a tiff file.

#### Version 5.2

- Improved the bundled A2V2 disk-exchange program: it is now also able to transfer "copy-protected" disk images from an Apple II to the Macintosh.
- The Z80 card was not detected on an Intel Mac, and hence didn't work. This has been fixed.
- Fixed an issue with license key validation when Japanese is the system default language.
- Fixed an issue with keyboard emulation: open apple + esc is now correctly forwarded to the Apple //e.
- Fixed an issue that could cause a ProDOS shared folder to report an I/O error when updating file metadata (like the binary load address).
- On the Apple ][ and ][+, the "Show 80 Column Video" menu sometimes failed to update the screen. This has been fixed.

#### Version 5.1

- The program now comes as a universal binary, fully compatible with both the Intel and the Power PC Macintoshes.
- Added emulation of the ImageWriter II printer.
- Fixed an issue in the mouse card; as a result the emulation now supports the Apple II program "Blazing Paddles".
- Improved disk drive timing: as a result the Apple II program "Wasteland" now runs from copy-protected (.nib) disk images.
- Changed the Mockingboard card in such a way that the Apple II program "SkyFox" now detects and uses the card.
- Added a configurable option to skip the "save state" dialog when closing a virtual machine.
- Fixed an issue that resulted in wrong game paddle values when the machine ran at high speed.
- Fixed a potential crash in the Inspector when analyzing some types of copy protected disks.
- The "soft caps lock" feature doesn't affect pasted text anymore; it only affects typed characters, as it should.
- Solved an issue in sound handling that could lead to a deadlock when resetting the virtual machine.
- The "relative mouse mode" setting is now stored when saving a configuration file.

#### Version 5.0

- Added a major new feature: the "Inspector". It allows to closely watch the behavior of the virtual machine and debug Apple II programs.
- Made the "speed dial" options more accessible by assigning keyboard shortcuts to them.
- Improved compatibility of the simple text printer.
- Solved a bug that caused wrong license key evaluation when Japanese was the system default language.

#### Version 4.3

This is a bug-fix release.

- Solved an issue in the built-in Spotlight module, which could cause endless rescanning of hard disk image files.
- The Spotlight module now does a better job in recognizing the file system on diskette image files. It sometimes skipped valid DOS images.
- Improved the compatibility of the A2V2 program, to support more types of USB-to-serial adapters.

#### Version 4.2

- Added the option to convert diskettes from and to a real Apple II via a serial cable.
- Added emulation of the "no-slot clock".
- It is now possible to print text to the Macintosh clipboard.
- A configured machine can now be made the default machine in one simple step.
- The Preferences window has an option to open the devices drawer to either the bottom or the right side of the window. Opening it on the right side is particularly useful on small screens.
- When an USB game pad is connected, it is now automatically the preferred choice for game control. It used to be a configurable option, but this could easily lead to a seemingly not-working game pad.
- Improved artwork of the Printer button: it finally looks like a printer.
- Solved problems with the game "Alternate Reality The Dungeon" by improving the emulation of the stepper motor in the diskette drive.

#### Version 4.1

- A Mac OS X folder can now be mounted as a ProDOS disk image, making it easy to share files and folders between the Apple II and Mac environments.
- The included Spotlight module now also scans ProDOS disks (OS X 10.4 "Tiger" only).
- The program now suports double low resolution graphics on the Apple //e.
- Solved a diskette compatibiliy problem; as a result the game "Alternate Reality The Dungeon" now runs.
- Solved a cassette port compatibility problem; as a result "Beyond Castle Wolfenstein" now runs.
- Solved a issue that could cause the machine to run too fast in "high speed" mode (it would behave like "maximum speed" instead).

#### Version 4.0

- Added a much requested feature: the Mockingboard emulation. This is a free upgrade for all licensed users.
- Changed the configuration of the default machine to include the Mockingboard in slot 4.
- Solved a bug that could cause failure to read a saved state file.

#### Version 3.5.1

- Fixed a bug that caused the Epson emulation to render text in a much too small font. This occurred in OS X 10.4 only.
- Made some subtle timing adjustments in disk I/O; as a result the "Apple Cider Spider" game now runs.

#### Version 3.5

- The program is now fully OS X 10.4 "Tiger" compatible. The program still runs on Panther, provided the version is 10.3.9. The program does not run on OS X 10.2 "Jaguar" anymore.
- Included a Tiger Spotlight module that allows fast searching for Apple ][ files.
- A diskette image can now be inserted in the virtual machine by double-clicking it in the Finder, or selecting it in Spotlight.
- Improved compatibility of the emulated mouse. As a result, it is now possible to run the "GEOS" program.
- Included a link to the new Virtual ][ Forum in the Help menu.
- The 6502 an Z80 engines now benefit from the additional speed of the G5 processor, if available. The program is still fully compatible with the G3 and G4 processors.
- Fixed a bug that caused some solid apple key combinations (like solid apple-N) to be ignored.
- Fixed some bugs with Macintosh folders mounted as DOS diskettes.
- Fixed some minor problems in the 65C02 implementation, increasing general compatibility.
- Solved a bug in the mouse card firmware; it can now handle interrupt mode and should therefore now work in any Apple ][ program.
- Fixed a bug in Apple IIe memory-bank switching, improving general compatibility

#### Version 3.4.1

- Corrected an issue introduced in the 3.4 version, that could cause CP/M to fail during boot.

#### Version 3.4

- Added emulation of the Grappler+ printer interface card. The previously used "generic" printer card is now obsolete and can no longer be selected.
- The emulated Epson FX-80 now supports user-defined characters.
- Improved quality of high resolution graphics rendering. In particular text rendered as graphics is now more readable.
- Reviewed and improved handling of the internal ROM on the Apple //e; as a result the overall compatibility has been improved.
- Improved the maximum speed of the emulated processors (both 6502 and Z80A) by about 10%.
- Improved behavior of the analog game inputs when resuming a virtual machine. Effectively, this means a game can be resumed in a more controlled way.
- Changed the "underscore" character on the Apple //e to more closely match the original.
- Solved a bug that could cause a clobbered display when scrolling the print preview.
- Solved a bug in handling graphics printing in the Epson FX-80 emulation.
- Solved a bug in the disk drive that could cause ProDOS to get stuck in an endless loop.

#### Version 3.3

- The program now produces the sounds of the disk drives and the matrix printer.
- Solved a bug that could assign the wrong file type to a new diskette image file.
- Solved a bug in the Epson FX-80 configuration window that was likely to crash the program.

#### Version 3.2

- Further improved the sound quality of the emulated internal speaker.
- Added the "variable speed" option, to speed up lengthy operations.
- Solved a bug that could cause a valid license code to be rejected.

#### Version 3.1

- Improved the rendering of double high resolution graphics; the emulation now accurately emulates an NTSC monitor. Effectively this improves the graphics quality and the readability of text in programs like Dazzle Draw or Apple Desktop.
- Improved accuracy of low-resoution colors and double high resolution colors.
- Improved the efficiency of high resolution rendering by about 25%. As a result, the "Solid Hi-Res" option is now obsolete and has been removed from the program (this was an option to gain efficiency at the expense of accuracy).
- Significantly improved sound quality of the emulated internal speaker.
- Added a toolbar for easier access of common functions.
- The "Screen" menu is now named "View" and has been extended with toolbar-related commands.
- The sound volume can now be changed.
- Added a menu command / toolbar button to open a Finder window with the folder where your disk images are; in combination with Mac OS X "Exposé" this is a comfortable way to quickly select a disk image and drag it to a drive.
- An alias file of a disk image is now accepted when dropped on a drive (the alias file must have the proper extension though).
- The program can now automatically adjust the Mac monitor resolution when going to full-screen mode. This solves perfomance issues on big screens.
- The Apple //e, not the ][+, is now the default machine when the program is first started.
- A "saved state" file gets a custom icon that is a miniature representation of the emulated screen.
- Solved a bug: when the mouse was switched on and off (by the Apple II software) in rapid succession, this could block the Virtual ][ user interface. This occurred in Dazzle Draw for example.
- Solved a bug that prevented full-screen mode to work correctly in a multi-monitor setup.
- Solved a bug that was likely to crash the program when starting with a "default.vii" configuration file.

#### Version 3.0

- Added emulation of the Epson FX-80 printer (available in OS X 10.3 "Panther" or better).
- The state of a virtual machine can be saved so it can continue to run later on.
- Included support for the RamWorks card on the Apple //e. This card gives you up to 8 MB of memory, and replaces the "64K / 80 column card", which is now obsolete and no longer supported.
- The program now includes a number of different character sets ROM's and you can add your own character sets as well.
- Simplified the installation procedure for ROM image files. Previously ROM files had to have specific names; now the program automatically searches for a ROM file suitable for the machine to be emulated.
- The "phosphor" color of the monochrome screen can now be changed to any color; it used to be "green only".
- The video refresh rate of the emulated monitor can now be configured.
- When doing a cold restart of the emulated machine (ctrl-command-reset), the disks now stay in the disk drives.
- Improved compatibility of the mouse emulation; software like Apple //e Desktop now runs fine.
- Fixed a bug that made it impossible to remove a diskette image from a configuration.

#### Version 2.6

Many of the enhancements are the direct result of feedback I received from users. Thanks every-one!

- A floppy disk image can now be part of the configuration, making it possible to create a turnkey system with a bootable floppy disk image.
- A Macintosh folder can now be mounted as a DOS 3.3 floppy disk.
- Added a quick way to select between 3 different standard machines: Applel ][, Applel ][+ and Apple //e.
- Added the option to define a default configuration, which is used when the program starts.
- Introduced the option to use the Macintosh backspace key as left arrow key.
- Improved support for the Open Apple and Solid Apple key on the Apple //e.
- Added an optional disk I/O indicator light in full screen mode.
- Added the "Media" pull down menu, which contains all commands to insert disks and tapes.
- When a virtual machine window is closed the program now asks for a confirmation.
- The standard window size can now be set as an application-wide preference.
- Improved the efficiency of video rendering by about 30%.
- Solved a bug that prevented the game "Serpentine" to run.
- Solved a bug that corrupted the internal timing of a virtual machine after the Macintosh woke up from sleep mode (solved this in Panther, not in Jaguar).

#### Version 2.5.1

- Fixed a Jaguar compatibility issue introduced in version 2.5

#### Version 2.5

- Added support for ProDOS hard disk emulation.
- Added support for a USB joystick or game pad.
- Added emulation of a ProDOS compatible clock card.
- Improved the overall efficiency of the emulation engine by about 25%. Effectively, this means the virtual machine consumes less Macintosh processor time.
- Fixed a problem with keyboards that require the use of the "alt" key for some special characters like "@" and "#". These characters can now be entered in the normal way.

#### Version 2.1

- Added emulation of the Z80 card, so it is now possible to run CP/M.
- The speed of the 6502 processor can now be configured from 1 to 10 MHz.
- The Apple ][ screen can now be copied to the clipboard, either as graphics or as text.
- Added the possibility to pause / resume a virtual machine.
- Added support for the ".po" disk image format.
- Changes in disk images were only stored when the disk image was ejected. To prevent loss of data, a modified image is now also auto-saved at regular intervals (every 30 seconds).
- Added a number of "Great Apple ][ Links" under the Help menu.
- Changed the Reset key to function key F12 (was F13), because not all Macintosh keyboards have the F13 key.
- Pasting text in the Apple //e 80-column screen could lead to lost characters; fixed this problem.
- Solved an issue that prevented some versions of ProDOS to boot.
- Improved general compatibility of the emulated mouse card.
- Both the mouse and the game controls are operated by the Macintosh mouse. It appeared this caused problems in some Apple ][ programs. Solved this by disabling the game I/O while the Apple ][ mouse is switched on.

#### Version 2.0

This release adds much-requested features and a number of other improvements.

- Emulation of the Apple //e, including emulation of the 65C02 processor;
- Emulation of the Apple //e 80-column / 64K RAM card;
- Mouse card emulation;
- Full-screen support and multiple window sizes;
- Full, configurable support for the Game I/O connector;
- Added a configuration option to allow choosing betweeen predefined machine types (Apple ][, Apple ][+ or Apple //e). As a result, made some changes to the way ROM files are found. Existing users might have to change their configuration, as described in the documentation.
- Solved an issue that caused the program to crash when a disk was inserted while no disk drives were configured;
- Improved slot configuration: a card will now only fit in a slot where it will actually work.

#### Version 1.1

This release contains numerous new features and improvements.

- Now supports diskettes with up to 40 tracks (was 35).
- Added 80-column card and video soft-switch.
- Added configurable cassette tape playback volume, in order to allow reading a recording of an actual Apple ][ tape.
- File extensions .DSK and .NIB are now recognized as equivalent to .dsk amd .nib.
- Disk image type ".do" (or ".DO") is recognized as equivalent to .dsk. When the disk image is modified, the extension is changed to the more common ".dsk".
- The "View" menu has additional options and has been renamed "Quick settings".
- Push button 1 of the game controller can now be operated with the right mouse button or the alt key.
- Added keyboard shortcuts for frequently used menus, like show / hide devices and insert a disk.
- Improved behavior of empty slots, so software like ProDOS now recognizes them as "empty".
- Improved overall speed of the 6502 engine by about 30%. This does not mean the Apple ][ software runs faster; it means the emulator consumes less Macintosh processor time.
- Improved linefeed handling by the emulated printer; as a result it does not produce superfluous empty lines anymore.
- Added "floating bus" support in the I/O addresses of the video generator. This undocumented feature is used in some games. As a result compatibility has been improved.
- Solved a bug with respect to the "shift key modification". In release 1.0, I had assumed that pressing the shift key "pressed" the game controller button. It appeared the 80-column card expects pressing shift releases the game controller button.
- Solved a bug in handling of expansion ROM (on a card). This improves general compatibility.

#### Version 1.0

Initial release

###

Specifications of the virtual machine

CPU
  MCS6502 / SY6502, running at 1.023 MHz to 10.230 MHz (configurable). Only the "official" instruction set is supported; all other opcodes are treated as NOP.
  WDC 65C02, running at 1.023 MHz to 10.230 MHz (configurable).
Main board
  Apple II revision 1.
  Apple //e revision B.
Video generator
  Supports text, low resolution graphics and high resolution graphics. Screen refresh rate is configurable at 10, 15, 20, 30, or 60 Hz.
  On Apple //e also supports 80-column display and double hires.
Character generator ROM
  Can be configured to display only upper case characters or upper and lower case characters.
  On the Apple //e, contains the regular and alternate character sets.
  Allows installation of a custom character set.
Monitor
  Configurable color or monochrome. Size can be set to 560 x 384 pixels (i.e. 1 Apple ][ pixel is presented as 2 x 2 Macintosh pixels), 840 x 576 (1 pixel is 3 x 3), 1120 x 768 ( 1 pixel is 4 x 4), or full-screen.
  Monochrome "phosphor" color can be configured.
ROM memory
  12 KB configurable from an external file. Memory range $D000 to $FFFF. If the external file contains less than 12K of data, the top part of memory is set up using the file, and the remaining bytes are initialized to 0.
  The Apple //e has 16K of ROM, and uses the last 16K of the ROM file.
RAM memory
  Apple ][(+): configurable in sizes 4K, 8K, 12K, 16K, 20K, 24K, 32K, 36K and 48K.
  Apple //e: fixed 64 KB; can be upgraded up to 8 MB with the RamWorks card.
Sound
  The "speaker toggle" mechanism of the Apple ][ is fully implemented using the Macintosh sound manager.
Cassette interface
  Using the built-in cassette recorder module, sound produced by the Apple ][ on the cassette output connector can be recorded to an AIFF file, and (uncompressed) AIFF files can be read and fed to the cassette input connector.
Game connector
  All inputs of the game connector can be triggered with mouse and keyboard, or with a USB game device. The output functions (annunciators and C040 strobe) are not available.
Keyboard
  All Apple ][ keys are supported, except "REPT". Can be configured to enter upper case characters only, or upper and lower case characters; on an Apple ][(+) the shift key can be connected to operate button 2 of the game connector (the "shift key modification").
16 K RAM Card
  Implements the Ramex 16 card. Fully compatible with the UCSD Pascal system.
Saturn memory card
  Implements the Saturn Systems 128K memory card.
Apple ][ 80-column card
  Emulates the Term 80 Video Display Interface.
RamWorks III card (for Apple //e only)
  Configurable 64 KB to 8128 KB of RAM, with increments of 64 KB. Allows 80-column and double-hires display.
Parallel printer interface card
  Emulates the Orange Micro Grappler+ card. The DIP switches are pre-configured to support the Epson FX-80 printer.
Serial printer interface card
  Emulates the Apple Super Serial Card, with the DIP switches pre-configured to support the ImageWriter II printer.
Super Serial card
  Emulates the Apple Super Serial Card (SSC), except for the emulation mode of the older "Serial Interface card". The SSC emulation can work with real serial devices connected to the Macintosh, either via USB, Bluetooth, or a built-in modem.
Mouse card
  Emulates the AppleMouse // card.
Epson FX-80 printer
  Emulates all Epson FX-80 features except printing proportional characters. The output can be saved to a pdf file for further processing.
ImageWriter II printer
  Emulates all ImageWriter II features except printing proportional characters and selecting print quality. The output can be saved to a pdf file for further processing.
"Text only" printer
  Writes to an ASCII text file in append mode.
AppleClock card
  Emulates the Mountain Computer AppleClock. Is not compatible with the Apple //e.
Thunderclock card
  Emulates the Thunderware Thunderclock Plus.
No-slot clock
  Emulates the Dallas Phantom DS1216 SmartWatch/ROM Real-Time Clock.
SCSI card
  Can only be used with the ProDOS software interface for block devices. Does not actually support the SCSI standard and has no documented I/O addresses. Is designed to work with the OmniDisk emulated drive.
ProDOS disk drive ("OmniDisk")
  Emulates an imaginary disk drive able to work with ProDOS disk images of any size up to 32MB. The disk image formats supported are "hdv" and "2img".
Disk ][ card
  Emulates the Apple Disk ][ card for DOS 3.3 (16 sectors per track).
Disk ][ drive
  Supports up to 80 tracks (including half-tracks). Diskettes are implemented as disk image files or mounted Macintosh folders. Supports sector formats as well as nibble formats. Supports reading, writing and write protection.
Mockingboard card
  Emulates the type "A" (a.k.a. "Sound II") Mockingboard card, which means it contains two sound chips able to produce 6 simultaneous sound channels. It does not support the speech chip.
Z80 card
  Emulates the Zilog Z80A processor at a clock speed of either 2 MHz or 4 MHz (configurable).
Timing
  Timing of all instructions is as specified in the Synertec 6502 Programming Manual. The internal clock runs with an average speed of 1.023 MHz. This means that not every individual instruction is accurately timed; however the average timing is accurate when measured over longer time intervals.

###

Unsupported features

Not all Apple ][ hardware features are supported, and some things work slightly different.

- The Mountain Computer AppleClock emulation does not support setting the current time. It adjusts itself automatically according to the Macintosh system clock.
- The emulated Z80 processor does not implement the IN and OUT instructions, and does not implement interrupt handling. These are not severe limitations, because I/O is memory-mapped on the Apple ][, and because all interrupts generated by the virtual machine are supposed to be handled by the 6502 processor.
- The emulated matrix printers do not support proportional characters.
- The Super Serial card does not support emulation of the P8 and P8A versions of the Apple II Serial Interface card (SIC).
- The C040 strobe on the Game I/O connector is not supported, and will never be. According to Apple's documentation, this 5 volts line can be dropped to zero volts by an application, for the duration of one-half microsecond. Such a short event cannot be accurately emulated.

###

Why did I create this application?

I bought my first computer, an Apple ][ europlus, in early 1982. It had 48 KB of RAM, a monochrome green monitor, and one Disk ][ drive. It cost me an arm and a leg, but I never regretted the purchase. On the contrary, during the years I used the machine, from 1982 to 1986, it gave me enormous amounts of fun, and in the end it was worth every penny I paid for it. During that period, I purchased more and more add-on peripheral cards, like the 16K RAM card, a Z80 card, an 80-column card, a clock card, a printer card, a super serial card, and a PAL TV card (which allowed me to finally see the colors the Apple ][ produced, on a TV screen). I found lots of enjoyment in writing programs for the Apple ][, and in discovering exactly how everything worked. I did quite a bit of reverse engineering myself, and bought several technical books (see Acknowledgements). In 1986 I bought my first Macintosh, and soon the Apple ][ was moved to the basement. Ten years later, around 1996, I found that a number of very good Apple ][ emulators were available, like Stop The Madness (STM) and Catakig. One weekend, I got the Apple ][ from the basement, set it up on my desk, and to my surprise everything still worked without a problem. I connected the Apple ][ to the Macintosh with a serial cable, and created software on both machines to convert my many floppy disks to disk images on the Macintosh. Again to my surprise, all disks could be read without a problem despite their 10 year stay in the basement. In the end, I managed to convert all my disks, even the "copy protected" ones, like Bag of Tricks and Visicalc.

The purpose of this was just to enjoy the nostalgia and relive the magical early days of the home computer era. When I switched to Mac OS X in early 2002, I regretted that none of my favorite Apple ][ emulators were available in the new OS. Early 2003, I decided to try and write my own Apple ][ emulator. It seemed like a challenging and fun project, and so far it still is.

The 21-year old Apple ][ again played an important role in the realization of the Virtual ][ application; I used it for almost all of the photographs in the program, and to compare the behavior of the emulator with "the real thing".

###

Acknowledgements

Quick progress on the project was made possible by a few excellent books I purchased many years ago.

The "Apple ][ Reference Manual" came with the machine, and contains an accurate and detailed description of all built-in hardware elements. It formed the basis of the class design of the core library.

"Beneath Apple DOS" by Don Worth and Pieter Lechner was essential for the implementation of the disk drive emulation. To my knowledge it is the only book that describes the nibble encoding scheme used to store data on disk.

"Programming the 6502" by Rodnay Zaks has always been my reference to the 6502 instruction set.

"What's where in the Apple?" by William F. Luebbert was very helpful during troubleshooting and as a quick reference to the Apple ][ I/O addresses.